Database governance built for humans and agents — controlling changes and access across every major database.
Bytebase v1 API — audit, round two
What's wrong with the v1 API measured against aip.dev, in plain terms.
Audited against e09ef6867b (2026-09-03), whose line numbers these are. The August round was
security-first; this one takes the AIPs as the spine and checks the proto and the handler
separately, so "the proto says X" and "the server does X" are two different findings. All 218
RPCs across 36 files were linted; every standard method and most custom ones were traced through
handler and store. Findings are code-traced, not runtime-proven, except where noted. Go paths are
relative to backend/api/v1/ and proto paths to proto/v1/v1/ unless they carry a directory.
The short version
| Problem | Severity | |
|---|---|---|
| X1 | The "disable export" policy is enforced by the browser, not the server. Resolved: Export requires bb.sql.export, enforced on the server, and disable_export is removed |
HIGH |
| X2 | ListInstanceDatabase with an inline instance skips every SaaS credential guard the create path has |
HIGH |
| X3 | CreateRollout with target: "" deploys every stage; the proto says none |
HIGH |
| U1 | Instance and Project are rewritten whole from a cached copy with no lock — a rotated password can silently revert |
HIGH |
| U2 | Five Update methods return 500 when update_mask is omitted |
MED |
| U3 | Renaming a group orphans every IAM binding that names it | MED |
| U4 | Four Update methods accept unknown mask paths and report success; two mask vocabularies name fields the proto does not have |
MED |
| U5 | One UpdateSetting has two mask semantics, and three settings are read-modify-written from a cache with no lock |
MED |
| U6 | The two Batch*Update* methods are not atomic |
MED |
| N1 | stages/- is both a real stage name and the AIP-159 wildcard |
MED |
| N2 | Environment is the most-referenced noun in the API and is not a resource | MED |
| N3 | projects/- is documented on ListPlans and ListRollouts and works on neither |
MED |
| N4 | Plans are soft-deleted through UpdatePlan; there is no DeletePlan |
MED |
| L1 | A negative page_size is accepted everywhere and means 10 |
MED |
| L2 | Eleven List methods have no pagination and a twelfth ignores its own; six of them grow with data and none has a LIMIT |
MED |
| L3 | ListServiceAccounts/ListWorkloadIdentities parse a project filter and then drop it |
MED |
| L4 | SearchProjects filters by permission after paginating |
MED |
| L5 | Issue search replaces the caller's order_by with relevance ranking whenever query is set |
MED |
| C1 | GetDatabaseMetadata connects to the database and writes |
MED |
| C2 | Lifecycle codes disagree per resource: 200, NOT_FOUND, INVALID_ARGUMENT and INTERNAL for the same situations |
MED |
| C3 | CreatePolicy silently overwrites; two Creates answer a duplicate with INTERNAL |
MED |
| X4 | BatchUpdateIssuesStatus.parent is decorative; UpdateIssueComment discards the comment name's project |
MED |
| X5 | Six multi-minute RPCs run synchronously with no server-side timeout; Export buffers the file in memory |
MED |
| A1 | Six authenticated RPCs carry no auth_method, which silently means "any principal" |
MED |
| A2 | The permission the proto declares is not the one the handler checks, on four methods that publish it | MED |
| A3 | A request field that departs from the ACL extractor's naming convention is silently authorized at workspace scope | MED |
| V1 | Request validation covers 13% of string inputs and nothing bounds a request body | MED |
Everything LOW is in the sections, not the table.
Is there a tool for this?
Yes. api-linter, maintained by googleapis, is the linter the AIPs are
written for: one rule per AIP clause, checking proto shape — resource annotations,
standard-method signatures, HTTP bindings, field behaviors, pagination fields. It is installed
(~/go/bin/api-linter 1.72.0), and this round ran it over all 36 files with a config that turns
off the four rule families that do not apply here:
# proto/api-linter.yaml
- included_paths: ['v1/**/*.proto']
disabled_rules:
- 'core::0191' # Google-internal java/package layout
- 'core::0203::field-behavior-required' # every-field coverage: 2047, tracked separately
- 'core::0192::has-comments' # 1058, tracked separately
- 'client-libraries' # GAPIC generation rules
buf export proto -o /tmp/protos && cd /tmp/protos && api-linter -I . --config api-linter.yaml --set-exit-status v1/*.proto
| Findings | |
|---|---|
| Raw | 3845 |
| With the config | 575 |
| — annotation-only, nothing on the wire changes | 211 |
| — additive fields or RPCs | 23 |
| — wire-breaking: renamed RPCs, paths, fields or enums; pagination; request shapes | 237 |
| — domain-justified, suppress in place | 104 |
The 211 are one mechanical PR: singular/plural on every resource (66), IDENTIFIER on every
resource name (32), OPTIONAL on every update_mask (21), OUTPUT_ONLY on the seven state
fields, method_signature on 34 methods, snake_case pattern variables, and three missing
resource_references — the annotation the ACL interceptor keys on. The 237 are design decisions,
each a rename that breaks a client, and are what the sections below are about. The 104 are places
the AIP is wrong for this domain — from_title/to_title on a diff record, service_name for
an Oracle service, uint32 for a database value, a websocket that must be GET — and should be
suppressed in-file with a reason so they stop being counted:
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: IssueUpdate records a before/after pair. --)
What the linter cannot see is behavior: whether page_size is honored, whether an unsupported
filter field errors or is dropped, whether update_mask decides the write, whether a Get has
side effects, what Delete on a deleted resource returns. That is the second half of this audit,
done by hand, and it is where the HIGH findings are. There is tooling for that half too, of a
different kind: protoc-gen-go-aip-test
generates a Go conformance suite per service from the resource annotations (standard methods,
pagination, field masks, etags, soft delete, user-settable IDs), and
go.einride.tech/aip supplies the AIP-160 filter parser,
order_by validation, opaque page tokens and resource-name patterns that the hand-rolled handling
below reimplements. Both are experimental-grade and neither knows CEL, so they are a follow-up,
not a gate. The house pattern that already works for behavior is the descriptor-walking test —
TestAllowMissingCreatePermission — and A1 and A3 below are two more of those.
The gate is the linter. buf lint's BASIC profile, the only check CI runs
(.github/workflows/ci.yml:155), sees none of the 575, which is how they accumulated. A
ratchet — run api-linter --output-format json, compare the count against main, fail on
increase — is one workflow step and holds the line while the 211 are burned down; once they are,
--set-exit-status with the suppressions in place becomes the gate.
Custom methods that do something other than what they say
X1 · Export ignores the export policy — HIGH, resolved
QueryDataPolicy.disable_export is documented as "Disable data export in the SQL editor"
(proto/v1/v1/org_policy_service.proto:272). The backend never reads it: the only references are
the converter and the store (org_policy_service_converter.go:173, :183;
backend/store/policy.go:387, :401, :432), and SQLService.Export reads
getEffectiveQueryDataPolicy for row and size limits only (sql_service.go:1113). The console
hides the button (frontend/src/modules/sql-editor/components/ResultView/ResultView.tsx:144).
Anyone holding bb.databases.get and bb.sql.select on a database exports it through the API
with the policy on, and read-write MCP sessions get Export as a WRITE-class method. Bytebase's
own principle is that governance is enforced, not displayed. One refusal in the handler closes it.
Resolved. Export now requires bb.sql.export on the data it reads, held through a role or
a matching export grant, and the server enforces it for every caller: console, API and MCP.
disable_export is removed. See sql-export-permission.md.
X2 · ListInstanceDatabase is a connection probe that skips the create guards — HIGH
With instance set, the handler builds an unsaved instance from the request body and hands it
straight to GetInstanceMeta (instance_service.go:336-362), which opens an admin connection to
the caller-supplied host and runs a full SyncInstance (backend/runner/schemasync/syncer.go:428-449).
CreateInstance runs validateAndSanitizeDataSourceTLS and checkInstanceDataSources first
(instance_service.go:402-408); this path runs neither. On SaaS that means the probe accepts what
the create path refuses: an IAM data source with no credential, which connects as the host's own
cloud identity (validateIAMCredentialForSaaS, :745-774), and a Vault token sourced from a
server environment variable or file path (validateExternalSecretForSaaS, :811-839) — read by
the server and sent to a Vault URL the caller chose. The interceptor swaps the permission to
bb.instances.create for this mode (acl.go:236-241), so the exposure is bounded to instance
creators, but the create path they are bounded to has the guards and this one does not. The
proto declares bb.instances.get and a List (instance_service.proto:154-169); the OpenAPI
and MCP surfaces publish that.
X3 · CreateRollout with an empty target creates every stage — HIGH
The proto: "If set to "", no stages are created" (rollout_service.proto:311-314).
filterTasksByStage returns nil for "" (rollout_service.go:1337-1343), and BuildTasks
treats a nil task list as "compute all of them" (:441-447), so an explicit empty target produces
the full pipeline. Under an automatic rollout policy that is execution, not just rows. No in-tree
caller sends ""; an API client following the proto would.
X4 · Two batch/child shapes where the name does not decide — MED
BatchUpdateIssuesStatus takes parent plus a list of issue names; the handler never reads
parent and the interceptor authorizes the names individually (issue_service.go:1156-1165,
acl.go:702-706), so parent: projects/A with issues in B succeeds. AIP-234 wants
requests: repeated UpdateIssueRequest and the updated resources back; this returns nothing. The
store side is atomic (backend/store/issue.go:566-640), which is the part that matters most.
UpdateIssueComment carries the target in issue_comment.name under a PATCH …/issues/*:comment
path. The handler discards the name's project segment (issue_service.go:1324), checks only that
the issue UID matches (:1328-1330), and with allow_missing creates a new comment on parent
when the name pointed at another project (:1335-1348). Any holder of bb.issueComments.update
edits any comment; there is no creator check (:1355-1363). AIP-134: the path is
{issue_comment.name=…/issueComments/*} and the name decides.
X5 · Long-running work runs inline — MED
Query has no timeout unless the workspace query_timeout is set; the default is MaxInt64
(backend/store/setting.go:69-79, applied at sql_service.go:419-430). The HTTP server sets no
read or write timeout (backend/server/server.go:352-356). SyncDatabase and SyncInstance are
synchronous under a fifteen-minute deadline (database_service.go:482, instance_service.go:1108,
syncer.go:36); BatchSyncInstances loops them (:1139); CheckRelease runs SQL review and AI
lint per target with no bound but the request context (release_service_check.go:39-193).
Export builds the whole result and the zip in memory and returns it as bytes content
(sql_service.go:1156-1182), bounded by the 100 MB result policy and the gateway's 100 MB cap
(grpc_routes.go:276), base64-inflated over REST. AIP-151's rule of thumb is ten seconds;
RunPlanChecks and RunReview already have the right shape — a resource row and a scheduler
tickle — and Sync*/CheckRelease could take it.
Also, LOW
- Four methods named
Update*are not AIP-134 updates:UpdateEmail(POST, no mask, renames the resource),UpdateSavedQueryStar(one bool),UpdatePurchase(no resource; cancels the Stripe subscription before creating the next,subscription_service.go:203-223) andUpdateDatabaseCatalog(full replace, documented). Their URIs are already:updateEmail,:updateStar,:updatePurchase; only the RPC names claim to be standard. ListInstanceRolesdeclarespage_size/page_tokenand documents them as "Not used." (instance_role_service.proto:37-44).GetTaskRunLogreturns every log row with no limit (rollout_service.go:617,backend/store/task_run_log.go:60-70).GetTaskRunLogandGetTaskRunSessiontakeparenton aGet(rollout_service.proto:357-363,:783-788).AddDataSourceanswers a duplicate id withNOT_FOUND(instance_service.go:1218-1220).UploadLicenseisPATCH /v1/subscription/licensewith no resource or mask (subscription_service.proto:36-44);UndeleteReleasealone omitsbody: "*", so the gateway never decodes a body for it (release_service.proto:82-88,backend/generated-go/v1/release_service.pb.gw.go:309-327).GetCurrentUsertakesgoogle.protobuf.Empty(no room for a field) and isallow_without_credential, though the handler returnsUNAUTHENTICATEDwithout a token (user_service.go:133-135); the annotation only changes who emits the 401.- The three deprecated
SQLServicequery-history aliases have no HTTP binding and no in-tree callers outsidebackend/tests/query_history_test.go:368-407, but the MCP OpenAPI is generated with the Connect feature and no deprecation filter, so agents see six operation ids for three capabilities (backend/api/mcp/gen/openapi.yaml:5710-5870,openapi_index.go:170-190). No removal version is stated. - Saved-query sharing is
:getPolicy/:setPolicyreturningSavedQueryPolicywhile the permissions are namedbb.savedQueries.getIamPolicy/setIamPolicyand every other resource uses:getIamPolicy/:setIamPolicy→IamPolicy(saved_query_service.proto:158-177).
Update
Twenty-eight methods are named Update* or Batch*Update*; twenty-one carry an update_mask.
The mask is the AIP-134 contract: "the service must treat an omitted field mask as an implied
field mask equivalent to all fields that are populated", unknown paths are INVALID_ARGUMENT, and
the write is what the mask names.
U1 · Whole-document rewrites with no lock — HIGH
UpdateInstance, UpdateDataSource and AddDataSource clone the instance's cached metadata
(instance_service.go:871, :1280, :1228; backend/store/instance.go:73), apply the mask to
the clone, and write the whole JSONB column back without FOR UPDATE
(backend/store/instance.go:301-310). Two writers interleave and the second restores the first's
old document: a title edit racing a credential rotation puts the old password back, and nothing
reports it. UpdateProject does the same with setting (project_service.go:296, :382;
backend/store/project.go:302-316), and UpdateSetting(DATA_CLASSIFICATION) bulk-rewrites that
same column across every project (setting_service.go:485-500). UpdateDatabase shows the fix:
its label merge runs inside the row lock (backend/store/database.go:341-376). AIP-154's etag is
the API-visible half; the lock is the half that stops the data loss.
U2 · An omitted mask is a 500 — MED
UpdateDatabaseGroup (database_group_service.go:137), UpdateGroup (group_service.go:208),
UpdateReviewConfig (review_config_service.go:120), UpdateWebhook (project_service.go:854)
and UpdateIssueComment (issue_service.go:1310) read UpdateMask.Paths through a nil pointer.
No buf.validate rule covers any update_mask, so the panic is recovered by connect.WithRecover
into INTERNAL with a stack trace in the log (grpc_routes.go:127-131). The other sixteen check
for nil and answer INVALID_ARGUMENT. Three protos mark the mask REQUIRED (Plan, Issue,
IssueComment), and IssueComment is one of the five that panic on it. An empty, non-nil mask is
a third behavior: INTERNAL from the store for IdP, DatabaseGroup, ReviewConfig and Role
(backend/store/idp.go:236, database_group.go:148, review_config.go:183, role.go:231),
INVALID_ARGUMENT for five, a silent no-op write for the rest. One helper and one rule — reject
absent and empty masks, or implement AIP-134's implied mask — would replace three.
U3 · A group's name is a mask path — MED
groups/{email} is the group's identifier, and email is an accepted UpdateGroup path
(group_service.go:210-211). The store rewrites saved-query grants for the rename
(backend/store/group.go:342-350) and nothing else. IAM bindings hold group:{old email}, and
getGroupMembers resolves them by name (backend/component/iam/manager.go:155-160,
backend/store/group.go:56-74), so after a rename every binding that named the group resolves to
nothing: its members lose the roles, and a new group created with the old email inherits them.
AIP-203 IDENTIFIER exists so a linter can catch exactly this; name on Group carries
OUTPUT_ONLY instead (group_service.proto:233). UpdateEmail on users is the counter-example:
one transaction rewrites nineteen reference sites (backend/store/principal.go:632-1026).
U4 · Unknown paths that succeed, and paths the proto does not have — MED
UpdateIdentityProvider (idp_service.go:175), UpdateUser (user_service.go:405),
UpdateServiceAccount (service_account_service.go:258-259) and UpdateWorkloadIdentity
(workload_identity_service.go:246-247) skip paths they do not recognize and return 200. state
on those last three is therefore a silent no-op — which is at least the right outcome for a field
AIP-216 says an update must not touch. UpdateWebhook requires the path notification_type
(project_service.go:864) for the field the proto calls notification_types
(project_service.proto:594); UpdateSetting(APP_IM) requires value.app_im_setting_value.teams
(setting_service.go:518) for a message with no such field (setting_service.proto:136-148). A
client that spells the real field path is rejected and must learn the fake one from the source.
U5 · UpdateSetting has two contracts — MED
For MCP, AI, EMAIL, APP_IM and WORKSPACE_PROFILE the mask decides
(setting_service.go:194, :331, :409, :534, :715); for WORKSPACE_APPROVAL,
DATA_CLASSIFICATION, SEMANTIC_TYPES and ENVIRONMENT it is ignored and the value is replaced
whole (:226, :268, :307, :368), with cross-resource effects — deleting an environment
clears it from every instance and database (:380-398). Of the masked five, APP_IM and
WORKSPACE_PROFILE write under UpdateSettingAtomic's row lock (:574, :797;
backend/store/setting.go:419) while MCP, AI and EMAIL read the cache and upsert
(:168, :334, :417 → :465) — the hazard GetSettingUncached documents
(backend/store/setting.go:286-290). Two admins saving SMTP or the AI key revert each other.
U6 · Batch updates are loops — MED
BatchUpdateInstances (instance_service.go:1183-1189) and BatchUpdateDatabases
(database_service.go:542-548) call the singular handler in a loop; a failure on item n leaves
items before it applied and reports one error. AIP-234: "Synchronous batch update must be
atomic." BatchDeleteProjects was fixed to one transaction in August; these two were not.
Also
allow_missingis implemented on every method that declares it (sixteen; none is dead), but the interceptor's.update→.createrewrite derives the wrong permission for two:UpdateWebhookdemandsbb.projects.createandUpdateDataSourcebb.instances.create(acl_allow_missing_test.go:38,:46) whereAddWebhook/AddDataSourceneed only.update.UpdateIssueandUpdateIssueCommentre-check the create permission at workspace scope only (issue_service.go:908,:1337;backend/component/iam/manager.go:71-72) after a project-scoped interceptor pass, so a project-scoped principal is denied the upsert it could do throughCreate. MED.UpdateReleasealways returnsUNIMPLEMENTED(release_service.go:245) while the proto advertises a mask, audit and anallow_missingits request does not have (release_service.proto:56-66,:185-191). LOW.UpdateDatabaseCatalogis a full replace with no etag (database_catalog_service.go:121,:135); its proto blames AIP-161, which forbids addressing an element ofschemas, notschemasitself. Two admins classifying different tables overwrite each other. MED, known since August.UpdateServiceAccountrotates the key whenservice_keyis in the mask and ignores the value sent (service_account_service.go:245-256) — a custom method hiding in a mask path.UpdateEmailto the same address isINVALID_ARGUMENT(user_service.go:614), so it is not idempotent. LOW.UpdateInstancerecodesNOT_FOUNDasINVALID_ARGUMENTand keysallow_missingon the error string"not found"(instance_service.go:852,:865). LOW.UpdateSetting.validate_onlyechoes the request rather than the merged result for the masked settings (setting_service.go:458-463);APP_IMdoes it right (:566-569). LOW.- Responses:
UpdateDataSourcereturns theInstance,UpdateWebhooktheProject,UpdateSavedQueryStara truncatedSavedQuerywithstarredpatched from the request (saved_query_service.go:556-557,:583),UpdateWorkspaceechoes the request'snamewhile ignoring it for identification (workspace_service.go:158,:189). LOW.
List
The paginated lists share parseLimitAndOffset (common.go:358-378): default 10, maximum 1000,
and a page token that is base64 of {limit, offset} (:321-356) — decodable, forgeable, and not
bound to the filter, order or parent it was issued for. next_page_token is empty exactly when a
limit+1 probe found nothing more, which is right, and every default ordering ends in a primary
key, which August fixed.
L1 · Negative page_size means 10 — MED
limit <= 0 maps to the default (common.go:373-375); ListTaskRuns maps it to 1000
(rollout_service.go:380-382). AIP-158: "If the user specifies a negative value for page_size,
the API must send an INVALID_ARGUMENT error." Six handlers already do this by hand —
ListIssues, SearchIssues, ListIssueComments, ListReleases, ListSavedQueries,
SearchSavedQueries (issue_service.go:275, release_service.go:181,
saved_query_service.go:151) — so the surface disagrees with itself; one line in the helper ends
that. In the same helper, token.limit is sign-checked and token.offset is not (:365-370), so
a forged negative offset reaches OFFSET -n and surfaces as INTERNAL.
L2 · Unbounded lists — MED
Eleven List RPCs have no pagination fields: ListDatabaseGroups, ListIdentityProviders,
ListInstanceDatabase, ListPolicies, ListReleaseCategories, ListReviewConfigs, ListRoles,
SearchSavedQueryFolders, ListSettings, ListPurchasePlans, ListWorkspaces; a twelfth,
ListInstanceRoles, has them and ignores them. AIP-158 is blunt: pagination goes in "at the
outset" because "adding pagination to an existing RPC is a backwards-incompatible change" — the
client that never read next_page_token gets a silently shorter list the day it appears. Six of
the twelve are bounded by nature: settings by enum, roles, review configs, identity providers,
purchase plans, the caller's workspaces. The other six grow with data and none has a LIMIT:
ListPolicies with projects/- or environments/- returns every policy of every project
(backend/common/resource_name.go:817-831; backend/store/policy.go:661-695);
ListInstanceDatabase and ListInstanceRoles return whatever the remote server has, the first
after a full SyncInstance (X2); ListDatabaseGroups, ListReleaseCategories and
SearchSavedQueryFolders grow with the project. Four lists also have no ORDER BY at all —
policies, settings, review configs, roles — so their order is whatever PostgreSQL feels like
(backend/store/setting.go:307-318, review_config.go:57-72, role.go:149-203).
L3 · A filter that parses and is then dropped — MED
ListServiceAccounts and ListWorkloadIdentities share GetAccountListFilter, which turns
project == "projects/x" into TRUE plus a side-channel ProjectID (backend/store/account_filter.go:65-71);
ListUsers and ListGroups consume that side channel, these two handlers do not
(service_account_service.go:186, workload_identity_service.go:179). The caller gets every
account and no error. AIP-160: "If a non-compliant … filter string is specified, the API
should error with INVALID_ARGUMENT." Every other unsupported field in every CEL builder does
error; this one parses. Where the side channel is consumed it is applied as an inner join, so
a || project == p behaves as a && project == p (backend/store/principal.go:216-227,
group.go:106-118).
L4 · SearchProjects pages first and authorizes second — MED
When the caller lacks workspace-wide bb.projects.get, the handler runs LIMIT/OFFSET, computes
next_page_token, and only then drops the projects the caller cannot see
(project_service.go:170-198): pages come back short or empty with a live token, and a client
that stops on an empty page loses data. This is the shape SearchWorksheets had until August
(T13), fixed there by pushing the predicate into SQL. The proto still carries // TODO(d): secure it. on the RPC (project_service.proto:60).
L5 · order_by is discarded when issue search has text — MED
ListIssues and SearchIssues validate order_by and then, whenever query produces a
full-text match, replace it with ts_rank(...) DESC (backend/store/issue.go:411-417,
:470-477) and answer 200. A client paging by create_time desc with a search term is paging by
relevance and does not know. AIP-132: honor it or reject it. August noted this and left it; it
belongs with L1–L4 as the same class — a request parameter silently redefined.
Also
state == "DELETED"is documented as a standalone filter on instances, projects, users, service accounts and workload identities and matches nothing unlessshow_deletedis also set, becausedeleted = falseis still ANDed in (backend/store/instance.go:124-126,project.go:127-129,principal.go:256-258); the console works around it (frontend/src/stores/app/instance.ts:354). LOW.- Filter docs drift from code in both directions:
ListDatabasessupportsname ==and documents only.contains();!( … )works around any sub-expression and is documented forengine inonly;ListProjectsomitsexclude_default;ListInstances.stateaccepts bare enum names while accounts also acceptSTATE_. LOW. - Wildcard rejection has four spellings:
projects/-isNOT_FOUNDonListDatabases,INVALID_ARGUMENTonListInstances, an empty 200 onListServiceAccounts, and supported onListPolicieswithout being documented (database_service.go:305-314,instance_service.go:528-531,service_account_service.go:149-155). N3 covers the two that document it and fail. LOW. ListPolicies.show_deletedmeans "includeenforce = false"; policies have no soft delete (org_policy_service.go:115).ListDatabases.show_deleted = falsealso hides live databases on archived instances (backend/store/database.go:172-175).BatchGetDatabases.nameshas nomax_itemsand an empty list is a 200. LOW.ListServiceAccounts/ListWorkloadIdentitiesannotateparentasbytebase.com/Projectand acceptworkspaces/{id}; the handlers check the prefix only, so workspace correctness rests on the interceptor's mismatch check alone (service_account_service.go:156-159,acl.go:161-166). LOW.- Filters that widen instead of failing: a mistyped
ListChangelogsstatusvalue becomes enum zero and thenDONE(changelog_service.go:69-71,:303-304);ListReleasescategory == ""is dropped and the list comes back unfiltered (release_service.go:220-222);status == A && status == Bon issues collapses toANY(A, B), which is OR (issue_service.go:124,backend/store/issue.go:421-427).ExportAuditLogsrequires a non-emptyfilterand its proto does not say so (audit_log_service.go:101-103). LOW. - Filter literals that panic: an unchecked
value.(string)on issuecreator/status/type(issue_service.go:120-132) and plancreator(backend/store/plan.go:282), andAsLiteral()on a non-literal.contains()argument (backend/store/query_history.go:312,plan.go:353), are recovered intoINTERNALwith a stack trace per request; an unknown user in an issuecreatorfilter isINTERNALtoo (issue_service.go:140-143). Same class as U2. LOW. ListInstanceRoles.refresh"will refresh and return the latest data" (instance_role_service.proto:52-53) and is never read (instance_role_service.go:28-37). LOW.
Get, Create, Delete
C1 · A Get that connects and writes — MED
GetDatabaseMetadata runs a remote SyncDatabaseSchema and persists the result when no schema
is cached (database_service.go:654-670). A read that can block on, fail from, and mutate state
through the customer's database is not a Get (AIP-131). GetPolicy synthesizes an unsaved
default rollout policy when none exists (org_policy_service.go:62-70, :322-346) — harmless,
but a Get that returns something that is not stored.
C2 · Lifecycle answers differ per resource — MED
AIP-164 is specific: soft-deleted resources come back from Get with state: DELETED; a Delete
on one "should error with NOT_FOUND"; an Undelete on a live one "must respond with
ALREADY_EXISTS". Here:
| Project | Instance | User / SA / WI | Release | |
|---|---|---|---|---|
Get when deleted |
resource | resource | resource | NOT_FOUND (release_service.go:166-169) |
Delete when deleted |
200 no-op (project_service.go:427-429) |
200, re-runs the archive (instance_service.go:1023-1027) |
NOT_FOUND |
NOT_FOUND |
Undelete when live |
200 (:450-452) |
200 (:1052-1055) |
INVALID_ARGUMENT (user_service.go:559-561) |
200 (:280-301) |
DeleteReviewConfig and DeleteRevision return 200 for a name that does not exist
(review_config_service.go:154-162, revision_service.go:263-274), and DeleteRevision
re-stamps deleter on an already-deleted row. DeleteWorkspace twice is INTERNAL
(workspace_service.go:296-298). The last-admin guard and undelete-on-live are
INVALID_ARGUMENT where AIP-193 says FAILED_PRECONDITION. Every soft delete returns Empty
where AIP-135 says the resource, so callers re-Get to see the state. Same client logic, seven
outcomes.
C3 · Duplicates — MED
CreatePolicy is an upsert: a second create with the same type overwrites the masking or rollout
policy and answers 200 (backend/store/policy.go:753, :856). CreateGroup and
CreateDatabaseGroup let the unique-index error through as INTERNAL (group_service.go:142-145,
database_group_service.go:84-87). AIP-133: ALREADY_EXISTS. The other seven Creates with a
client-chosen id get this right.
C4 · Existence before permission — MED, accepted in August
The interceptor resolves every project, instance and database name before it checks the
permission (acl.go:145-148 then :172-186), so a name that does not exist is NOT_FOUND for
any authenticated caller and a name that does is PERMISSION_DENIED — an enumeration oracle for
project ids, workspace instance ids and database names inside the workspace. The comment at
acl.go:159-160 accepts authenticated probing; AIP-193 does not ("regardless of whether or not it
exists, the service must error with PERMISSION_DENIED"). Restated, not re-litigated: the
August disposition stands unless the workspace is meant to hold mutually untrusted members.
Also
GetIssue.forceis never read (issue_service.go:63-73).CreateReviewConfigalone takes its id from the body'sname(review_config_service.go:214-221) instead of areview_config_id.ServiceAccount/WorkloadIdentityids are validated as email local parts, not as resource ids (service_account_service.go:62-80).CreateInstance.validate_onlysucceeds before the instance-count and activation guards run (instance_service.go:412-428). LOW.DeleteProjecttakes noforceand checks no children; project instances and their databases becomeNOT_FOUNDbehind it (instance_service.go:1636-1638). Hard deletes leave referents:DeleteGroupleaves bindings,DeleteDatabaseGroupleaves plan specs,DeleteIdentityProviderleaves bound users,DeleteReviewConfigdetaches tag policies after the delete and outside the transaction (review_config_service.go:164-200).DeleteRoleis the model:FAILED_PRECONDITIONnaming the bindings (role_service.go:209-227). LOW.purgeonDeletecites AIP-165, which defines a collection-levelPurgemethod, not a flag. No RPC takes arequest_id(AIP-155); onlyCreateSheet(content hash) and plan-linkedCreateIssueare naturally idempotent. LOW.
Resource model
N1 · stages/- means two things — MED
A stage whose environment is unset or deleted is named stages/-
(backend/common/resource_name.go:737, EmptyStageID), and so is every task and task run under
it. The same character is the AIP-159 wildcard the parsers honor — a - at the stage position is
any stage (resource_name.go:399, :454). ListTaskRuns(parent: ".../stages/-/tasks/-"), the
documented way to read a whole rollout (rollout_service.proto:320), is also the only name a
client has for the environment-less stage, and answers with every stage's runs. BatchRunTasks
and BatchSkipTasks parse the parent's stage as a wildcard and then ignore it, reading the stage
from each task name instead (rollout_service.go:781, :821-826), where
formatEnvironmentFromStageID maps - back to "" (rollout_service_converter.go:18-22). Two
meanings, routed differently by different methods. AIP-159: a URI pattern "must not
hard-code the - character". A real id (stages/unassigned) fixes it; breaking for any client
that stored a stages/- name, which the console does not.
N2 · Environment is not a resource — MED
environments/{environment} is a policy parent (org_policy_service.proto:193-195), a field on
Instance, Database, Stage and CreateRolloutRequest (instance_service.proto:575,
database_service.proto:532, rollout_service.proto:405, :314), a ReviewConfig resource
(review_config_service.proto:148), five filter grammars and every CEL condition. It has no
google.api.resource, so no resource_reference can point at it and the linter cannot check any
reference; and no Get or List: an environment is an element of the ENVIRONMENT setting
(setting_service.proto:564-580), whose only write is a whole-list replace through
UpdateSetting (U5). Consequences the agents traced: CreatePolicy under environments/nope
succeeds — nothing calls GetEnvironmentByID (org_policy_service.go:394-430,
backend/store/policy.go:743-746) — and deleting an environment clears it from instances and
databases but leaves its policies as rows that never apply (setting_service.go:382-400). A
declared bytebase.com/Environment with read-only Get/List is additive; the parent check is
one lookup.
N3 · Documented wildcards that fail — MED
ListPlans says "Use projects/- to list all plans from all projects" (plan_service.proto:125)
and passes - to the store as a project id (plan_service.go:99, backend/store/plan.go:141-142):
empty. ListRollouts says the same (rollout_service.proto:260) and calls GetProject("-"):
NOT_FOUND (rollout_service.go:128-141). SearchIssues, ListSavedQueries,
ListQueryHistories, ListTaskRuns, BatchCancelTaskRuns and the database batch methods do what
they document. The undocumented ones are the mirror: ListPolicies accepts projects/- and
environments/-, SearchAuditLogs accepts "" and projects/-, BatchRunTasks accepts
stages/- (N1), none says so. AIP-159: "The method must explicitly document that this behavior
is supported."
N4 · Plans are deleted through Update — MED
Plan.state can be DELETED, ListPlans filters on it (plan_service.proto:160), and the path
is UpdatePlan with update_mask: state (plan_service.go:318-319, written at :355). There is
no DeletePlan or UndeletePlan. AIP-216: "APIs should not allow a State enum to be
directly updated through an 'update' method." bb.plans.update — or being the creator, since
UpdatePlan is CUSTOM (plan_service.proto:61) — is enough to delete a plan, and a linked draft
issue's status moves with it (backend/component/review/plan.go:139-145). The other half of the
lifecycle is missing too: ListPlans and ListRollouts have no show_deleted and no deleted
predicate, so deleted plans are listed by default (backend/store/plan.go:127-191; the
malformed-plan filter explicitly keeps them, :162-163) and only an opt-in state == "ACTIVE"
hides them — the inverse of AIP-164. Database is the other resource with a DELETED state and
no Delete, correctly: sync owns it and the field is OUTPUT_ONLY (database_service.proto:516).
N5 · Undeclared and half-declared resources — LOW
bytebase.com/Workspace, AuditLog, IAMPolicy and DatabaseSchema are referenced by
resource_reference and declared nowhere (auth_service.proto:167, idp_service.proto:122,
workspace_service.proto:283, audit_log_service.proto:60, iam_policy.proto:19). Webhook
declares a pattern (project_service.proto:549-556) and has no Get, List, Create or
Delete; Add/Update/Remove return the Project, and RemoveWebhookRequest says the webhook
is "identified by its url" while the handler reads name (:523-525, project_service.go:902).
DataSource is the same embedded shape and declares nothing. Rollout is a singleton
(plans/{plan}/rollout) with a Create (AIP-156: "must not") and a ListRollouts over
projects/{project}/rollouts, a collection no pattern names; CreateRollout is in fact an
idempotent ensure that never answers ALREADY_EXISTS (backend/component/review/rollout.go:133-144),
which is the right behavior under the wrong name. PlanCheckRun next to it is the same shape done
right: RunPlanChecks on the plan, Cancel on the singleton.
N6 · Workspace addressing is two conventions — LOW
Explicit workspaces/{workspace} on databases, policies, service accounts, workload identities,
identity providers, IAM policy, TestEmailSetting and the workspace's own methods; implicit, from
the token, on users, groups, roles, projects, instances, settings, review configs and the
/v1/idps alias. The interceptor keeps the explicit form honest only where the field carries
resource_reference (acl.go:161-166): GetWorkspace.name, UpdateWorkspace.workspace.name,
DeleteWorkspace.name, LeaveWorkspace.name and TestEmailSetting.parent carry none
(workspace_service.proto:301-331, setting_service.proto:627). DeleteWorkspace checks by hand
(workspace_service.go:274-280); UpdateWorkspace ignores the name and patches the token's
workspace (:158); TestEmailSetting never reads parent; LeaveWorkspace acts on the named
workspace by membership while the ACL and the audit row belong to the token's
(:336-409). Self-hosted GetWorkspace(workspaces/{id}) is served without any auth check while
its comment claims the opposite (:81-82); the exposure is title and logo. SetIamPolicy accepts
workspaces/- in the handler and the interceptor rejects it first (:432-436, acl.go:387-393),
and the console falls back to that form (frontend/src/stores/app/iam.ts:282-286) — worth one
runtime check.
Also
/v1/idpsis a REST route that cannot succeed: since #21328parentis required with pattern^workspaces/[^/]+$(idp_service.proto:120-125), the validation interceptor runs first (grpc_routes.go:135-141), and the parentless binding (idp_service.proto:40) is still registered on the gateway (grpc_routes.go:316). Remove it. LOW.- Identity is the email:
users/{email},serviceAccounts/{email},workloadIdentities/{email}, andgroups/{group}where the segment is "email or uuid" (group_service.proto:233). No resource carries an AIP-148uid.UpdateEmailrewrites nineteen reference sites in one transaction and leaves three — auditresource/requesttext,login_attempt,email_verification_code— stale (backend/store/principal.go:632-1026). TheUNIMPLEMENTEDmessage on SaaS says "CreateUser" (user_service.go:582). LOW. - Instance and database names have two forms and no aliasing: a project instance cannot be
addressed as
instances/{id}and a workspace instance cannot be addressed under a project, at the store, the interceptor and every handler (backend/store/instance.go:108-113,acl.go:461-479,database_service.go:59-106); instance ids are workspace-global (LATEST.sql:544-546).SQLServicealone relies on the interceptor for it (sql_service.go:1927-1944). The canonical rule — nested iffinstance.projectis set — is implemented independently in seven emitters. Confirmed OK; noted because the seventh copy is where it will drift.
Authorization contract
A1 · Unset auth_method means "any principal" — MED
GetActuatorInfo, BatchParse, BatchDeparse, GetSubscription and ListPurchasePlans
carry no auth_method. doIAMPermissionCheck returns true for anything that is not
IAM (acl.go:254-256), so UNSPECIFIED and CUSTOM are indistinguishable to the interceptor and
the effective rule is "any authenticated member of the workspace" — right for all six today, and
the default an RPC gets by forgetting the annotation. Nothing rejects AUTH_METHOD_UNSPECIFIED:
TestLintEveryMethodIsClassified lints mcp_method_class only (mcp_gate_test.go:351-353). The
same descriptor walk, one more assertion.
A2 · The published permission is not the checked one — MED
The MCP OpenAPI publishes each method's permission option to agents; the
Permissions required: comment publishes it to the OpenAPI. Four methods publish one thing and
check another:
ListDatabasesdeclaresbb.databases.list(database_service.proto:59) and checks it for a workspace parent only; a project parent needsbb.projects.getand an instance parentbb.instances.get(database_service.go:297-336). The comment says so; the option does not.SearchMyAccessGrantsdeclaresbb.accessGrants.get(access_grant_service.proto:85) and checks nothing, scoping tocreator == caller(access_grant_service.go:421-442); a Workspace Member, who holds only.create, calls it successfully. Open since August.GetSetting/UpdateSettingdeclarebb.settings.get/.setand enforce narrowerEnvironmentSettings*/WorkspaceProfileSettings*permissions for two settings (setting_service.go:100-109,:153-162);Policymethods likewise split into masking sub-permissions (org_policy_service.go:458-488). A Workspace Member reads the environment and profile settings the declared permission would deny.DiffSchemadeclaresbb.databases.getand returns migration DDL derived from the schema (database_service.proto:189), which every other schema read gates onbb.databases.getSchema.
The other eleven CUSTOM methods that declare a permission check exactly it, with documented creator/owner/member bypasses. The fix is one of two: make the annotation mean something on CUSTOM methods by having the handler declare its check where a test can read it, or drop it from CUSTOM methods so the MCP OpenAPI stops publishing a contract nobody enforces.
A3 · The resource extractor still fails silent — MED
getResourceFromSingleRequest picks the one resource a request is authorized on by field-name
convention — parent, else name, else resource, else project, else the nested
<snake_case(resource)>.name for Create/Update/Remove/Test — and returns "" when
nothing matches, which the caller turns into a workspace-scope check (acl.go:747-810,
:524-529). Two RPCs have already been found that way, by sweep rather than by failure
(UpdateDatabaseCatalog and BatchDeleteProjects, both special-cased above it). The next request
whose field departs from the convention arrives scoped to the workspace and nothing reports it.
A startup or test-time walk that fails on a Create/Update/Delete request resolving to ""
is the same descriptor test as A1; it has been open since August.
A4 · The permission comment — LOW
proto/v1/v1/README.md makes // Permissions required: mandatory. Twenty-seven RPCs have none:
all of AccessGrantService and SubscriptionService, four of WorkspaceService, the
parented Create/List on service accounts and workload identities, Chat, Signup,
SwitchWorkspace. On CUSTOM methods the line is the only contract, and there it is accurate
where checked: CreateRollout bb.rollouts.create (rollout_service.go:282-289),
BatchRunTasks/BatchSkipTasks/BatchCancelTaskRuns bb.taskRuns.create or a rollout-policy
role (:1368-1404), DeleteUser bb.users.delete, UndeleteUser bb.users.undelete. The
descriptor walk that pins A1 and A3 can require the line.
Also
- Verb vocabulary:
GetTaskRun,GetTaskRunLog,GetTaskRunSessionandPreviewTaskRunRollbackare gated bybb.taskRuns.list— there is notaskRuns.get;SearchIssuesbybb.issues.getandListIssuesbybb.issues.list, andprojectViewerholdsgetwithoutlist, so it can search issues and not list them (backend/store/predefined_roles.go:608-624);Query,ExportandDiffSchemabybb.databases.get; data sources and webhooks by the parent's.update;CancelPlanCheckRunby.run. Consistent within each family, so a custom role author has to read the proto rather than guess. LOW. Query/Exportbeyond the interceptor: per-statementbb.sql.select|dml|ddl|explain|infoon the new-ACL engines with CEL conditions, data-source selection by policy, masking unless explaining or under an unmasking grant, row/size/timeout caps (sql_service.go:1466-1520,:2068-2187,:733-750).Exportrequiresbb.sql.exportwhereQueryrequiresbb.sql.selectorbb.sql.info, which a JIT grant withexport == truesatisfies on its targets, and forces a read-only session (:1020-1033,:1097).- Anonymous surface: eleven RPCs accept a call with no credential, and none serves per-caller
data.
GetAuthenticationInfoandLoginresolve an explicitworkspaceregardless of membership (auth_service.go:141,:152-154), so a real workspace id answers 200 and a fake oneINVALID_ARGUMENT— the existence oracle accepted in August, since ids are random and not enumerable.ExchangeTokenanswers an unknown workload-identity email withNOT_FOUNDand a bad token withUNAUTHENTICATED(:1194-1196,:1214-1217) — an email oracle for that namespace. Self-hostedGetWorkspace(workspaces/{id})is served with no check at all (N6).GetPolicy/DeletePolicyanswerNOT_FOUNDbefore the permission check (org_policy_service.go:75-77,:280-283).Chatlets any authenticated principal, service accounts included, spend the workspace AI key. LOW.
Field behavior and validation
V1 · 13% validated, nothing bounded — MED
proto/v1/v1/VALIDATION_STANDARDS.md defines five size tiers. 39 of the 295 string and bytes
fields on request messages carry a buf.validate rule. The other 256 include every filter,
order_by, page_token, parent and name, QueryRequest.statement,
ExportRequest.statement, AdminExecuteRequest.statement, DiffSchemaRequest.schema and
CheckReleaseRequest.custom_rules. No connect.WithReadMaxBytes is set on the v1 handler chain
(grpc_routes.go:136-146); the OAuth2 and MCP endpoints bound their bodies
(backend/api/oauth2/oauth2.go:77, backend/api/mcp/server.go:132). A statement of a gigabyte or
a megabyte of CEL is parsed in full before any limit applies. A read limit on the chain plus
max_len on the free-text fields closes the large hole; the name fields want a pattern more
than a length, and field_behavior = REQUIRED is enforced by nothing — UpdateWebhook and
RemoveWebhook dereference a REQUIRED message that arrived nil (project_service.go:807, :902).
V2 · Annotations that say the opposite of the code — LOW
AccessGrant.creator is REQUIRED (access_grant_service.proto:104); the handler derives it from
the caller and says the field "is OUTPUT_ONLY and must never be trusted"
(access_grant_service.go:163-170). The identity-provider secrets and AISetting.api_key carry
SENSITIVE but not INPUT_ONLY (idp_service.proto:268, :292, :327;
setting_service.proto:559) and are redacted on every read (idp_service.go:468, :486, :523;
setting_service_converter.go:865), the way DataSource.password says it is
(instance_service.proto:722-725). The same redaction gives UpdateIdentityProvider a value
semantic the mask does not express — an empty secret means "keep the stored one"
(idp_service.go:185-194), so a secret cannot be cleared. Subscription.expires_time is AIP-148's
expire_time (subscription_service.proto:266). Seven state fields and thirty-two name fields
lack the behavior the AIPs assign them; those are in the 211.
Errors
E1 · No machine-readable reason — LOW
AIP-193: "All error responses must include an ErrorInfo within details." The API attaches
one custom detail, PermissionDeniedDetail (common.proto:264; acl.go:178, :214 and three
handlers), and otherwise a canonical code and prose. FAILED_PRECONDITION for "plan check still
running" and for "instance archived" are the same to a client. google.rpc.ErrorInfo{domain: "bytebase.com", reason: …} is additive, and PermissionDeniedDetail's three fields are its
metadata. The code choices themselves are mostly right; C2 lists the ones that are not.
Documentation
The linter counts 1058 missing comments: 365 messages, 312 fields, 338 enum values, 43 enums.
Every RPC has one. The gaps concentrate in the database_service.proto metadata tree and
instance_service.proto, which are also what the MCP OpenAPI is generated from
(proto/buf.gen.yaml:44-50), so an agent reading the schema meets EnumTypeMetadata with no
explanation. Enable core::0192::has-comments once messages and enums are covered; fields can
follow.
What I'd do, in order
- The three HIGH handler fixes, one PR each. X1 is resolved:
Exportrequiresbb.sql.export.ListInstanceDatabase's inline mode runsvalidateAndSanitizeDataSourceTLSandcheckInstanceDataSourcesbefore it dials (X2).CreateRolloutwithtarget: ""creates nothing, or rejects the value (X3). Each is a few lines and a test. - Row locks under the three read-modify-write paths (U1, U5): instance
metadata, projectsetting, and theMCP/AI/EMAILsettings, usingUpdateSettingAtomicand theUpdateDatabaselabel-merge shape that already exist. Etags can follow; the lock is what stops the loss. - One mask rule for twenty-one methods (U2, U4): a shared
requireUpdateMaskthat rejects nil and empty withINVALID_ARGUMENT— the semantic three protos already declare — and rejects every path the handler does not know, plus a table test that calls eachUpdatewith a nil mask and withno_such_field. Fix the two fake vocabularies while there. - Group rename (U3): either rewrite bindings in the store transaction the way
UpdateEmaildoes, or takeemailout of the mask and marknameIDENTIFIER. The second is smaller. - The linter ratchet and the 211-annotation PR, in that order, so the PR is measured. Then
the three
resource_references the ACL keys on, and the in-file suppressions for the 104. - Three more descriptor-walking assertions (A1, A3, A4): no
AUTH_METHOD_UNSPECIFIED, no write request that resolves to the workspace by falling through the extractor, and aPermissions required:line on every RPC. Decide whatpermissionmeans on a CUSTOM method and make the MCP OpenAPI publish only what is true (A2). - Pagination where it is still cheap (L1–L5): negative
page_sizeerrors inparseLimitAndOffset;page_size/page_tokenonListDatabaseGroups,ListPolicies,ListReleaseCategories,SearchSavedQueryFoldersand a renamed:listDatabasescustom method now, before more clients exist;ORDER BYon the four lists that have none; the droppedprojectfilter (L3) andSearchProjects(L4) pushed into SQL as T13 was; issue search rejectsorder_bywithqueryor honors it (L5). - Names (N1–N4):
stages/unassigned; a read-onlyEnvironmentresource and a parent check inCreatePolicy;DeletePlan/UndeletePlanandstateout ofUpdatePlan's mask; the two wildcard docs made true or removed. - Body limit and validation (V1):
WithReadMaxByteson the chain,max_lenon the five free-text fields,patternon names as they are touched. - Long-running work (X5): server timeouts first, then
Sync*andCheckReleaseonto theRunPlanChecksshape.
Everything marked LOW is cleanup that rides along with whichever file is next opened.