Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
chore(doc): add plan for audit coverage (#21155)
ecmadaoaa91731f506d
diff --git a/docs/superpowers/plans/2026-08-12-v1-api-audit-coverage.md b/docs/superpowers/plans/2026-08-12-v1-api-audit-coverage.mdnew file mode 100644index 0000000000..a0439003aa--- /dev/null+++ b/docs/superpowers/plans/2026-08-12-v1-api-audit-coverage.md@@ -0,0 +1,734 @@+# V1 API Audit Coverage Implementation Plan++> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.++**Goal:** Add reliable, non-secret-bearing audit records for the uncovered V1 security and mutation APIs while explicitly preserving the intentional opt-outs for high-volume reads, synchronization, token refresh, and worksheet autosave.++**Architecture:** Keep the existing proto-driven audit interceptor as the single audit path. Each covered RPC receives `option (bytebase.v1.audit) = true`; `backend/api/v1/audit.go` remains responsible for canonical resource extraction and cloning/redacting request and response messages before serialization. Unauthenticated handlers resolve a validated workspace through `common.SetAuditWorkspaceID`, and focused end-to-end tests verify that annotations result in persisted rows rather than merely changing descriptors.++**Tech Stack:** Protocol Buffers, Connect RPC, Go, `protoregistry`, `protojson`, Bytebase audit interceptor/store, Testify, backend integration test harness.++## Global Constraints++- Never put credentials, tokens, raw SQL, AI prompts, worksheet content, exported files, license text, webhook URLs, or payment-session data in an audit request or response.+- Every redactor must clone before modification; `getRequestString` and `getResponseString` must not mutate live handler messages.+- Audit parents must be canonical `workspaces/{workspace}` or `projects/{project}` names; project-scoped actions must not leak into the workspace-scoped audit stream.+- Keep `Refresh`, `SyncDatabase`, `BatchSyncDatabases`, `SyncInstance`, `BatchSyncInstances`, `UpdateWorksheet`, `UpdateWorksheetOrganizer`, and `BatchUpdateWorksheetOrganizer` unaudited in this change.+- Keep `SwitchWorkspace` unaudited because it changes session/token context rather than workspace resources or authorization grants.+- Keep `TestWebhook` unaudited because it sends a synthetic outbound probe without changing persisted project configuration.+- Keep POST-based searches, CEL parse/deparse, schema diffs, release checks, instance database discovery, and rollback previews unaudited.+- Do not add blanket auditing to worksheet reads in the legacy service. The saved-query migration owns metadata-only search and conditional auditing for another user's private content.+- Run the repository's proto workflow after every proto batch: `buf format -w proto`, `buf lint proto`, then `(cd proto && buf generate)` so later commands remain at the repository root.+- Run `gofmt -w` on modified Go files and the focused Go tests after each task. Run the full Go lint/build gates before completion.++---++## Coverage Decision++Audit these 27 RPCs in this plan:++| Family | RPCs |+| --- | --- |+| Core lifecycle | `SetupSample`, `CreateProject`, `UpdateProject`, `RunPlanChecks`, `CancelPlanCheckRun`, `DeleteRelease`, `UndeleteRelease`, `BatchCreateRevisions`, `DeleteRevision` |+| Content-bearing lifecycle | `CreateRelease`, `UpdateRelease`, `CreateWorksheet`, `DeleteWorksheet` |+| Authentication | `RequestPasswordReset`, `ResetPassword` |+| Project webhooks | `AddWebhook`, `UpdateWebhook`, `RemoveWebhook` |+| Subscription | `UploadLicense`, `CreatePurchase`, `UpdatePurchase`, `CancelPurchase`, `ExportVCSProviderUsers` |+| Sensitive external actions | `AIService.Chat`, `AuditLogService.ExportAuditLogs`, `IdentityProviderService.TestIdentityProvider`, `SettingService.TestEmailSetting` |++The password-reset RPCs have one deliberate limitation: when the unauthenticated flow has no validated workspace, there is nowhere to persist a workspace-owned audit row. Both `RequestPasswordReset` and the corresponding successful `ResetPassword` therefore remain unaudited for codes issued without workspace context. Workspace-bound flows must be recorded.++---++### Task 1: Low-Risk Lifecycle Audit Coverage++**Files:**+- Modify: `proto/v1/v1/actuator_service.proto`+- Modify: `proto/v1/v1/project_service.proto`+- Modify: `proto/v1/v1/plan_service.proto`+- Modify: `proto/v1/v1/release_service.proto`+- Modify: `proto/v1/v1/revision_service.proto`+- Modify: `backend/api/v1/audit.go`+- Modify: `backend/api/v1/audit_test.go`+- Modify: `backend/api/v1/audit_redaction_test.go`+- Test: `backend/tests/login_audit_test.go`+- Test: `backend/tests/project_instance_test.go`+- Generated: `backend/generated-go/v1/`, `frontend/src/types/proto-es/v1/`, `proto/gen/grpc-doc/`, `backend/api/mcp/gen/`++**Interfaces:**+- Consumes: existing `getRequestResource(any) string`, `maskedString`, `proto.CloneOf`, and proto `bytebase.v1.audit` extension.+- Produces: audited descriptors, canonical resource names, and clone-first project payload redaction for nine lifecycle RPCs.++- [ ] **Step 1: Extend the resource extraction test first**++Add cases to `TestProjectLifecycleAuditResource` and rename it to `TestLifecycleAuditResource`:++```go+{name: "create project", request: &v1pb.CreateProjectRequest{ProjectId: "project-a", Project: &v1pb.Project{}}, want: "projects/project-a"},+{name: "update project", request: &v1pb.UpdateProjectRequest{Project: &v1pb.Project{Name: "projects/project-a"}}, want: "projects/project-a"},+{name: "run plan checks", request: &v1pb.RunPlanChecksRequest{Name: "projects/project-a/plans/101"}, want: "projects/project-a/plans/101"},+{name: "cancel plan checks", request: &v1pb.CancelPlanCheckRunRequest{Name: "projects/project-a/plans/101/planCheckRun"}, want: "projects/project-a/plans/101/planCheckRun"},+{name: "delete release", request: &v1pb.DeleteReleaseRequest{Name: "projects/project-a/releases/release-a"}, want: "projects/project-a/releases/release-a"},+{name: "undelete release", request: &v1pb.UndeleteReleaseRequest{Name: "projects/project-a/releases/release-a"}, want: "projects/project-a/releases/release-a"},+{name: "batch create revisions", request: &v1pb.BatchCreateRevisionsRequest{Parent: "instances/instance-a/databases/database-a"}, want: "instances/instance-a/databases/database-a"},+{name: "delete revision", request: &v1pb.DeleteRevisionRequest{Name: "instances/instance-a/databases/database-a/revisions/101"}, want: "instances/instance-a/databases/database-a/revisions/101"},+```++Change the assertion to `require.Equal(t, test.want, getRequestResource(test.request))`.++- [ ] **Step 2: Run the unit test and verify the new cases fail**++Run:++```bash+go test ./backend/api/v1 -run '^TestLifecycleAuditResource$' -count=1+```++Expected: FAIL for plan, release, and revision cases because `getRequestResource` currently returns an empty string.++- [ ] **Step 3: Add canonical resource extraction**++Add direct cases to `getRequestResource`; do not introduce another dispatcher:++```go+case *v1pb.RunPlanChecksRequest:+ return r.GetName()+case *v1pb.CancelPlanCheckRunRequest:+ return r.GetName()+case *v1pb.DeleteReleaseRequest:+ return r.GetName()+case *v1pb.UndeleteReleaseRequest:+ return r.GetName()+case *v1pb.BatchCreateRevisionsRequest:+ return r.GetParent()+case *v1pb.DeleteRevisionRequest:+ return r.GetName()+```++- [ ] **Step 4: Add failing project payload redaction tests**++In `backend/api/v1/audit_redaction_test.go`, add request cases for both project mutations with `secretSentinel` in a nested webhook URL:++```go+{"create project webhook URL", &v1pb.CreateProjectRequest{Project: &v1pb.Project{+ Webhooks: []*v1pb.Webhook{{Name: "projects/project-a/webhooks/webhook-a", Url: secretSentinel}},+}}},+{"update project webhook URL", &v1pb.UpdateProjectRequest{Project: &v1pb.Project{+ Name: "projects/project-a",+ Webhooks: []*v1pb.Webhook{{Name: "projects/project-a/webhooks/webhook-a", Url: secretSentinel}},+}}},+```++Add a response case for `Project` with the same nested webhook URL. Extend `TestAuditRedactionDoesNotMutateInput` with a project response and assert its original webhook URL remains `secretSentinel` after serialization.++- [ ] **Step 5: Run the redaction tests and verify they fail**++```bash+go test ./backend/api/v1 -run '^TestAudit(Request|Response)RedactsCredentials$' -count=1+```++Expected: FAIL because project request and response payloads currently serialize webhook URLs unchanged.++- [ ] **Step 6: Implement clone-first project redaction**++Add the nested webhook and project redactors to `backend/api/v1/audit.go`:++```go+func redactWebhook(w *v1pb.Webhook) *v1pb.Webhook {+ if w == nil {+ return nil+ }+ cloned := proto.CloneOf(w)+ if cloned.Url != "" {+ cloned.Url = maskedString+ }+ return cloned+}++func redactProject(p *v1pb.Project) *v1pb.Project {+ if p == nil {+ return nil+ }+ cloned := proto.CloneOf(p)+ for i, webhook := range cloned.Webhooks {+ cloned.Webhooks[i] = redactWebhook(webhook)+ }+ return cloned+}+```++Register `CreateProjectRequest` and `UpdateProjectRequest` in `getRequestString`, cloning the outer request and replacing its nested project with `redactProject`. Register `Project` in `getResponseString`. Preserve project IDs, update masks, names, webhook names/types/titles, and all other non-secret fields.++- [ ] **Step 7: Annotate the low-risk RPCs**++Add this option inside each RPC block for `SetupSample`, `CreateProject`, `UpdateProject`, `RunPlanChecks`, `CancelPlanCheckRun`, `DeleteRelease`, `UndeleteRelease`, `BatchCreateRevisions`, and `DeleteRevision`:++```proto+option (bytebase.v1.audit) = true;+```++- [ ] **Step 8: Generate and run focused unit tests**++Run:++```bash+buf format -w proto+buf lint proto+(cd proto && buf generate)+gofmt -w backend/api/v1/audit.go backend/api/v1/audit_test.go backend/api/v1/audit_redaction_test.go+go test ./backend/api/v1 -run '^(TestLifecycleAuditResource|TestAudit(Request|Response)RedactsCredentials|TestAuditRedactionDoesNotMutateInput)$' -count=1+```++Expected: all commands PASS.++- [ ] **Step 9: Add persistence regression coverage for the original symptom**++In `backend/tests/login_audit_test.go`, reuse `ctl.project`, which `StartServerWithExternalPg` already created through `ProjectService.CreateProject`. Query workspace audit logs with:++```go+Filter: `method == "/bytebase.v1.ProjectService/CreateProject"`,+```++Scan the method-matched rows for `Resource == ctl.project.Name` and require exactly one such row; do not assert that the method filter itself returns only one row because setup or future fixtures may create other projects. Assert that row has the workspace parent. Update `ctl.project`, query its project-scoped audit stream for `ProjectService/UpdateProject`, and assert the resource is `ctl.project.Name`.++In `backend/tests/project_instance_test.go`, immediately after the project-scoped instance is created, query its project audit stream for:++```go+Filter: `method == "/bytebase.v1.InstanceService/CreateInstance"`,+```++Assert a row exists with `Resource == projectInstance.Name`. This pins the distinction between “descriptor is annotated” and “row was actually persisted.”++- [ ] **Step 10: Run the lifecycle integration tests**++Run:++```bash+go test -v -count=1 ./backend/tests -run '^(TestAuditLogFormat|TestProjectInstanceCoreBehavior)$' -timeout 10m+```++Expected: PASS, including persisted `CreateProject`, `UpdateProject`, and `CreateInstance` rows.++- [ ] **Step 11: Commit the low-risk batch**++```bash+git add proto/v1/v1/actuator_service.proto proto/v1/v1/project_service.proto proto/v1/v1/plan_service.proto proto/v1/v1/release_service.proto proto/v1/v1/revision_service.proto backend/api/v1/audit.go backend/api/v1/audit_test.go backend/api/v1/audit_redaction_test.go backend/tests/login_audit_test.go backend/tests/project_instance_test.go backend/generated-go/v1 frontend/src/types/proto-es/v1 proto/gen/grpc-doc backend/api/mcp/gen+git commit -m "feat: audit core lifecycle APIs"+```++---++### Task 2: Release and Worksheet Content Redaction++**Files:**+- Modify: `proto/v1/v1/release_service.proto`+- Modify: `proto/v1/v1/worksheet_service.proto`+- Modify: `backend/api/v1/audit.go`+- Modify: `backend/api/v1/audit_redaction_test.go`+- Modify: `backend/api/v1/audit_test.go`+- Test: `backend/tests/login_audit_test.go`+- Generated: `backend/generated-go/v1/`, `frontend/src/types/proto-es/v1/`, `proto/gen/grpc-doc/`, `backend/api/mcp/gen/`++**Interfaces:**+- Consumes: `getRequestString`, `getResponseString`, `maskedString`, and `proto.CloneOf`.+- Produces: `redactRelease`, `redactWorksheet`, and redacted create/update request handling.++- [ ] **Step 1: Add failing request and response redaction cases**++Add `secretSentinel` as a release statement and worksheet content in `TestAuditRequestRedactsCredentials`, and add a worksheet response case in `TestAuditResponseRedactsCredentials`:++```go+{"release SQL", &v1pb.CreateReleaseRequest{Release: &v1pb.Release{Files: []*v1pb.Release_File{{Statement: []byte(secretSentinel)}}}}},+{"worksheet SQL", &v1pb.CreateWorksheetRequest{Worksheet: &v1pb.Worksheet{Content: []byte(secretSentinel)}}},+```++```go+{name: "worksheet response SQL", response: &v1pb.Worksheet{Content: []byte(secretSentinel)}},+```++- [ ] **Step 2: Run the redaction tests and verify they fail**++```bash+go test ./backend/api/v1 -run '^TestAudit(Request|Response)RedactsCredentials$' -count=1+```++Expected: FAIL because the sentinel appears in serialized audit payloads.++- [ ] **Step 3: Implement clone-first content redactors**++Add these helpers to `audit.go`:++```go+func redactRelease(r *v1pb.Release) *v1pb.Release {+ if r == nil {+ return nil+ }+ cloned := proto.CloneOf(r)+ for _, file := range cloned.Files {+ file.Statement = nil+ }+ return cloned+}++func redactWorksheet(r *v1pb.Worksheet) *v1pb.Worksheet {+ if r == nil {+ return nil+ }+ cloned := proto.CloneOf(r)+ cloned.Content = nil+ return cloned+}+```++Add request switch cases for `CreateReleaseRequest`, `UpdateReleaseRequest`, and `CreateWorksheetRequest`, preserving all non-content fields and update masks. Add response switch cases for `Release` and `Worksheet` so future handler changes cannot expose statement/content fields through the audit response.++- [ ] **Step 4: Add resource extraction, project ownership, and annotations**++Extend `getRequestResource`:++```go+case *v1pb.CreateReleaseRequest:+ return r.GetParent()+case *v1pb.UpdateReleaseRequest:+ return r.GetRelease().GetName()+case *v1pb.CreateWorksheetRequest:+ return r.GetParent()+case *v1pb.DeleteWorksheetRequest:+ return r.GetName()+```++Add `audit = true` to `CreateRelease`, `UpdateRelease`, `CreateWorksheet`, and `DeleteWorksheet`.++Ensure both worksheet lifecycle RPCs publish their owning project through the authorization context so the interceptor persists their audit rows under `projects/{project}`, not the workspace fallback. The implementation may use the existing declarative resource metadata or an equivalent project-resolution path; the required contract is project-scoped audit ownership.++- [ ] **Step 5: Verify redaction and persisted ownership**++Extend `TestAuditRedactionDoesNotMutateInput` with a release and worksheet, call the corresponding audit serializer, and assert the original statement/content still equals `secretSentinel`.++Extend the audit integration coverage to create and delete a worksheet, then query the project audit stream and assert both rows use `projects/{project}` as their parent. This test must fail if either action is filed only in the workspace audit stream.++- [ ] **Step 6: Generate and test**++```bash+buf format -w proto+buf lint proto+(cd proto && buf generate)+gofmt -w backend/api/v1/audit.go backend/api/v1/audit_redaction_test.go backend/api/v1/audit_test.go+go test ./backend/api/v1 -run '^(TestAudit(Request|Response)RedactsCredentials|TestAuditRedactionDoesNotMutateInput|TestLifecycleAuditResource)$' -count=1+go test -v -count=1 ./backend/tests -run '^TestAuditLogFormat$' -timeout 10m+```++Expected: PASS, no sentinel in any serialized payload, and worksheet lifecycle rows are discoverable in the owning project's audit stream.++- [ ] **Step 7: Commit the content-bearing batch**++```bash+git add proto/v1/v1/release_service.proto proto/v1/v1/worksheet_service.proto backend/api/v1/audit.go backend/api/v1/audit_redaction_test.go backend/api/v1/audit_test.go backend/tests/login_audit_test.go backend/generated-go/v1 frontend/src/types/proto-es/v1 proto/gen/grpc-doc backend/api/mcp/gen+git commit -m "feat: audit release and worksheet lifecycle"+```++---++### Task 3: Password Reset Security Events++**Files:**+- Modify: `proto/v1/v1/auth_service.proto`+- Modify: `backend/api/v1/auth_service.go`+- Modify: `backend/api/v1/audit.go`+- Modify: `backend/api/v1/audit_redaction_test.go`+- Test: `backend/tests/login_audit_test.go`+- Generated: `backend/generated-go/v1/`, `frontend/src/types/proto-es/v1/`, `proto/gen/grpc-doc/`, `backend/api/mcp/gen/`++**Interfaces:**+- Consumes: `common.SetAuditWorkspaceID`, `parseOptionalWorkspace`, and existing `redactLoginResponse`.+- Produces: `redactResetPasswordRequest` and validated workspace attribution for password-reset events.++- [ ] **Step 1: Add failing credential-redaction tests**++Add a request case containing the sentinel in password-reset `code` and `new_password`. Assert the email remains visible while both secrets are absent.++- [ ] **Step 2: Implement request redactors**++```go+func redactResetPasswordRequest(r *v1pb.ResetPasswordRequest) *v1pb.ResetPasswordRequest {+ if r == nil {+ return nil+ }+ cloned := proto.CloneOf(r)+ cloned.Code = maskedString+ cloned.NewPassword = maskedString+ return cloned+}+```++Register the helper in `getRequestString`. Keep `RequestPasswordResetRequest` unchanged because email and workspace are audit identifiers, not credentials.++- [ ] **Step 3: Attribute successful and target-valid auth events**++For `RequestPasswordReset`, set the audit workspace only after establishing both of these facts:++- the normalized email belongs to an active `END_USER` account;+- the requested workspace is valid for that account under the existing membership rules.++An `allUsers` workspace binding alone must not make an unknown, deleted, service-account, or workload-identity email auditable. Keep the endpoint's current always-success response and do not surface lookup failures; an absent, malformed, unknown, or invalid workspace produces no audit row.++For `ResetPassword`, attribute the event only to the validated non-empty workspace captured with the verification code. Set that workspace early enough that membership, password-policy, or update failures after successful code verification can be recorded. Do not invent or select an arbitrary workspace when the code has no workspace context; that path is the explicit no-workspace limitation described above.++- [ ] **Step 4: Add audit annotations**++Add `audit = true` to `RequestPasswordReset` and `ResetPassword`.++- [ ] **Step 5: Add auth persistence tests**++Extend `backend/tests/login_audit_test.go` to assert:++- a workspace-bound successful password reset row contains the email but neither the submitted code nor new password;+- a workspace-bound request for an active end user produces a row while preserving the endpoint's always-success response;+- unknown, deleted, service-account, and workload-identity emails do not create request audit rows, including when the workspace grants `allUsers`;+- no-workspace request and reset flows preserve their existing API behavior but create no audit row, documenting the storage limitation explicitly.++- [ ] **Step 6: Generate and run auth tests**++```bash+buf format -w proto+buf lint proto+(cd proto && buf generate)+gofmt -w backend/api/v1/auth_service.go backend/api/v1/audit.go backend/api/v1/audit_redaction_test.go backend/tests/login_audit_test.go+go test ./backend/api/v1 -run '^(TestAudit(Request|Response)RedactsCredentials|TestAuditRedactionDoesNotMutateInput)$' -count=1+go test -v -count=1 ./backend/tests -run '^TestAuditLogFormat$' -timeout 10m+```++Expected: PASS with no auth credential present in stored request/response JSON.++- [ ] **Step 7: Commit the authentication batch**++```bash+git add proto/v1/v1/auth_service.proto backend/api/v1/auth_service.go backend/api/v1/audit.go backend/api/v1/audit_redaction_test.go backend/tests/login_audit_test.go backend/generated-go/v1 frontend/src/types/proto-es/v1 proto/gen/grpc-doc backend/api/mcp/gen+git commit -m "feat: audit authentication security events"+```++---++### Task 4: Subscription and Export Audit Coverage++**Files:**+- Modify: `proto/v1/v1/subscription_service.proto`+- Modify: `backend/api/v1/audit.go`+- Modify: `backend/api/v1/audit_redaction_test.go`+- Generated: `backend/generated-go/v1/`, `frontend/src/types/proto-es/v1/`, `proto/gen/grpc-doc/`, `backend/api/mcp/gen/`++**Interfaces:**+- Consumes: workspace parent fallback from the authenticated context.+- Produces: `redactUploadLicenseRequest`, empty/redacted purchase responses, and metadata-only HTTP export responses.++- [ ] **Step 1: Add failing redaction cases**++Cover `UploadLicenseRequest.License`, `PurchaseResponse.PaymentUrl`, `PurchaseResponse.SessionId`, and `google.api.HttpBody.Data` with `secretSentinel` in the request/response redaction tables.++- [ ] **Step 2: Implement subscription redactors**++```go+func redactUploadLicenseRequest(r *v1pb.UploadLicenseRequest) *v1pb.UploadLicenseRequest {+ if r == nil {+ return nil+ }+ return &v1pb.UploadLicenseRequest{License: maskedString}+}++func redactPurchaseResponse(r *v1pb.PurchaseResponse) *v1pb.PurchaseResponse {+ if r == nil {+ return nil+ }+ return &v1pb.PurchaseResponse{}+}+```++For `google.api.HttpBody`, retain only `ContentType` and drop `Data` and `Extensions`. Register these types in the request/response serializer switches.++- [ ] **Step 3: Add subscription annotations**++Add `audit = true` to `UploadLicense`, `CreatePurchase`, `UpdatePurchase`, `CancelPurchase`, and `ExportVCSProviderUsers`.++Leave `Resource` empty for these workspace-singleton operations; the authenticated workspace remains the audit parent. Do not invent a non-resource-format subscription name.++- [ ] **Step 4: Generate and test**++```bash+buf format -w proto+buf lint proto+(cd proto && buf generate)+gofmt -w backend/api/v1/audit.go backend/api/v1/audit_redaction_test.go+go test ./backend/api/v1 -run '^(TestAudit(Request|Response)RedactsCredentials|TestAuditRedactionDoesNotMutateInput)$' -count=1+```++Expected: PASS; license, checkout URL/session, and CSV data are absent.++- [ ] **Step 5: Commit the subscription batch**++```bash+git add proto/v1/v1/subscription_service.proto backend/api/v1/audit.go backend/api/v1/audit_redaction_test.go backend/generated-go/v1 frontend/src/types/proto-es/v1 proto/gen/grpc-doc backend/api/mcp/gen+git commit -m "feat: audit subscription management actions"+```++---++### Task 5: Webhook, Configuration Test, AI, and Audit Export Actions++**Files:**+- Modify: `proto/v1/v1/project_service.proto`+- Modify: `proto/v1/v1/idp_service.proto`+- Modify: `proto/v1/v1/setting_service.proto`+- Modify: `proto/v1/v1/ai_service.proto`+- Modify: `proto/v1/v1/audit_log_service.proto`+- Modify: `backend/api/v1/audit.go`+- Modify: `backend/api/v1/audit_redaction_test.go`+- Modify: `backend/api/v1/audit_test.go`+- Generated: `backend/generated-go/v1/`, `frontend/src/types/proto-es/v1/`, `proto/gen/grpc-doc/`, `backend/api/mcp/gen/`++**Interfaces:**+- Consumes: existing `redactIdentityProvider`, `redactSetting`, and `maskedString`.+- Produces: metadata-only audit payloads for outbound tests, AI calls, and audit-log exports.++- [ ] **Step 1: Add failing secret/content tests**++Add cases for OAuth/OIDC authorization code, LDAP password, SMTP password, AI message content/tool arguments/provider metadata, exported audit-log bytes, and identity-provider response claims/user info. The shared project redactor from Task 1 already covers webhook URLs in webhook requests and returned `Project` responses. Keep safe identifiers such as project name, webhook name/title, recipient email, IdP name, AI token usage, and export page token.++- [ ] **Step 2: Extract a reusable email-setting redactor**++Create `redactEmailSetting(*v1pb.EmailSetting) *v1pb.EmailSetting` by moving the existing SMTP-password masking logic out of `redactSetting`; make `redactSetting` call it. Use the same helper for `TestEmailSettingRequest` so the two paths cannot drift.++- [ ] **Step 3: Implement request/response redactors**++Implement these exact contracts:++```go+func redactTestIdentityProviderRequest(r *v1pb.TestIdentityProviderRequest) *v1pb.TestIdentityProviderRequest+// Clone; call redactIdentityProvider; mask OAuth/OIDC code and LDAP password.++func redactTestIdentityProviderResponse(r *v1pb.TestIdentityProviderResponse) *v1pb.TestIdentityProviderResponse+// Return an empty response; provider claims and mapped email, title, and phone are identity data, not audit metadata.++func redactAIChatRequest(r *v1pb.AIChatRequest) *v1pb.AIChatRequest+// Return an empty AIChatRequest so prompts, tool schemas, tool arguments, and provider metadata are never logged.++func redactAIChatResponse(r *v1pb.AIChatResponse) *v1pb.AIChatResponse+// Return a response containing only a cloned Usage message.++func redactExportAuditLogsResponse(r *v1pb.ExportAuditLogsResponse) *v1pb.ExportAuditLogsResponse+// Return only NextPageToken; drop Content.+```++Register Add/Update/Remove webhook requests using Task 1's `redactWebhook`, and register `TestIdentityProviderRequest`, `TestIdentityProviderResponse`, `TestEmailSettingRequest`, `AIChatRequest`, `AIChatResponse`, and `ExportAuditLogsResponse` in the serializer switches. Add response-side sentinel cases for both `TestIdentityProviderResponse.Claims` and `TestIdentityProviderResponse.UserInfo`, and assert the serialized response is empty.++- [ ] **Step 4: Add canonical resource extraction**++```go+case *v1pb.AddWebhookRequest:+ return r.GetProject()+case *v1pb.UpdateWebhookRequest:+ return r.GetWebhook().GetName()+case *v1pb.RemoveWebhookRequest:+ return r.GetWebhook().GetName()+case *v1pb.ExportAuditLogsRequest:+ return r.GetParent()+case *v1pb.TestEmailSettingRequest:+ return r.GetParent()+```++The IdP test and AI chat remain workspace-parented with an empty resource because neither request names a canonical Bytebase resource.++- [ ] **Step 5: Add annotations**++Add `audit = true` to `AddWebhook`, `UpdateWebhook`, `RemoveWebhook`, `TestIdentityProvider`, `TestEmailSetting`, `AIService.Chat`, and `ExportAuditLogs`.++- [ ] **Step 6: Generate and test**++```bash+buf format -w proto+buf lint proto+(cd proto && buf generate)+gofmt -w backend/api/v1/audit.go backend/api/v1/audit_redaction_test.go backend/api/v1/audit_test.go+go test ./backend/api/v1 -run '^(TestAudit(Request|Response)RedactsCredentials|TestAuditRedactionDoesNotMutateInput|TestLifecycleAuditResource)$' -count=1+```++Expected: PASS; audit rows retain action metadata without outbound payloads or credentials.++- [ ] **Step 7: Commit the sensitive-action batch**++```bash+git add proto/v1/v1/project_service.proto proto/v1/v1/idp_service.proto proto/v1/v1/setting_service.proto proto/v1/v1/ai_service.proto proto/v1/v1/audit_log_service.proto backend/api/v1/audit.go backend/api/v1/audit_redaction_test.go backend/api/v1/audit_test.go backend/generated-go/v1 frontend/src/types/proto-es/v1 proto/gen/grpc-doc backend/api/mcp/gen+git commit -m "feat: audit sensitive outbound actions"+```++---++### Task 6: Lock the Audit Policy and Run Full Verification++**Files:**+- Create: `backend/api/v1/audit_policy_test.go`+- Modify: `docs/design/v1-api-audit-2026-08.md`++**Interfaces:**+- Consumes: generated method descriptors and `v1pb.E_Audit`.+- Produces: a regression guard for required annotations and documented intentional exclusions.++- [ ] **Step 1: Add the descriptor policy test**++Create a table-driven test using `protoregistry.GlobalFiles.FindDescriptorByName`. The helper must fail when a named method is missing or its audit extension is absent/false:++```go+func requireAuditedMethod(t *testing.T, fullName string) {+ t.Helper()+ descriptor, err := protoregistry.GlobalFiles.FindDescriptorByName(protoreflect.FullName(fullName))+ require.NoError(t, err)+ method, ok := descriptor.(protoreflect.MethodDescriptor)+ require.True(t, ok)+ options := method.Options().(*descriptorpb.MethodOptions)+ require.True(t, proto.HasExtension(options, v1pb.E_Audit), fullName)+ audited, ok := proto.GetExtension(options, v1pb.E_Audit).(bool)+ require.True(t, ok)+ require.True(t, audited, fullName)+}+```++`TestRequiredAPIAuditCoverage` must enumerate every RPC in the Coverage Decision table. Keep the method list explicit so reviewers can see policy changes in code review.++```go+func TestRequiredAPIAuditCoverage(t *testing.T) {+ for _, method := range []string{+ "bytebase.v1.ActuatorService.SetupSample",+ "bytebase.v1.AIService.Chat",+ "bytebase.v1.AuditLogService.ExportAuditLogs",+ "bytebase.v1.AuthService.RequestPasswordReset",+ "bytebase.v1.AuthService.ResetPassword",+ "bytebase.v1.IdentityProviderService.TestIdentityProvider",+ "bytebase.v1.PlanService.CancelPlanCheckRun",+ "bytebase.v1.PlanService.RunPlanChecks",+ "bytebase.v1.ProjectService.AddWebhook",+ "bytebase.v1.ProjectService.CreateProject",+ "bytebase.v1.ProjectService.RemoveWebhook",+ "bytebase.v1.ProjectService.UpdateProject",+ "bytebase.v1.ProjectService.UpdateWebhook",+ "bytebase.v1.ReleaseService.CreateRelease",+ "bytebase.v1.ReleaseService.DeleteRelease",+ "bytebase.v1.ReleaseService.UndeleteRelease",+ "bytebase.v1.ReleaseService.UpdateRelease",+ "bytebase.v1.RevisionService.BatchCreateRevisions",+ "bytebase.v1.RevisionService.DeleteRevision",+ "bytebase.v1.SettingService.TestEmailSetting",+ "bytebase.v1.SubscriptionService.CancelPurchase",+ "bytebase.v1.SubscriptionService.CreatePurchase",+ "bytebase.v1.SubscriptionService.ExportVCSProviderUsers",+ "bytebase.v1.SubscriptionService.UpdatePurchase",+ "bytebase.v1.SubscriptionService.UploadLicense",+ "bytebase.v1.WorksheetService.CreateWorksheet",+ "bytebase.v1.WorksheetService.DeleteWorksheet",+ } {+ t.Run(method, func(t *testing.T) {+ requireAuditedMethod(t, method)+ })+ }+}+```++- [ ] **Step 2: Add the intentional-exclusion test**++Add `requireUnauditedMethod` and enumerate the ten deliberate exclusions from Global Constraints. This makes adding audit to sync, autosave, session mechanics, or non-mutating probe paths a conscious policy change instead of accidental drift:++```go+func requireUnauditedMethod(t *testing.T, fullName string) {+ t.Helper()+ descriptor, err := protoregistry.GlobalFiles.FindDescriptorByName(protoreflect.FullName(fullName))+ require.NoError(t, err)+ method, ok := descriptor.(protoreflect.MethodDescriptor)+ require.True(t, ok)+ options := method.Options().(*descriptorpb.MethodOptions)+ if !proto.HasExtension(options, v1pb.E_Audit) {+ return+ }+ audited, ok := proto.GetExtension(options, v1pb.E_Audit).(bool)+ require.True(t, ok)+ require.False(t, audited, fullName)+}++func TestIntentionalAPIAuditExclusions(t *testing.T) {+ for _, method := range []string{+ "bytebase.v1.AuthService.Refresh",+ "bytebase.v1.AuthService.SwitchWorkspace",+ "bytebase.v1.DatabaseService.BatchSyncDatabases",+ "bytebase.v1.DatabaseService.SyncDatabase",+ "bytebase.v1.InstanceService.BatchSyncInstances",+ "bytebase.v1.InstanceService.SyncInstance",+ "bytebase.v1.ProjectService.TestWebhook",+ "bytebase.v1.WorksheetService.BatchUpdateWorksheetOrganizer",+ "bytebase.v1.WorksheetService.UpdateWorksheet",+ "bytebase.v1.WorksheetService.UpdateWorksheetOrganizer",+ } {+ t.Run(method, func(t *testing.T) {+ requireUnauditedMethod(t, method)+ })+ }+}+```++- [ ] **Step 3: Run the policy test**++```bash+gofmt -w backend/api/v1/audit_policy_test.go+go test ./backend/api/v1 -run '^Test(RequiredAPIAuditCoverage|IntentionalAPIAuditExclusions)$' -count=1+```++Expected: PASS with all required descriptors audited and all deliberate exclusions unaudited.++- [ ] **Step 4: Document the final policy**++Add an “Audit annotation coverage” section to `docs/design/v1-api-audit-2026-08.md` containing:++- the audited RPC families from the Coverage Decision table;+- the deliberate exclusions and their reasons, including session-only workspace switching and non-mutating webhook tests;+- the rule that serializers must redact credentials/content before annotations are enabled;+- the workspace-resolution limitation for both unauthenticated password-reset RPCs;+- the legacy worksheet-read deferral to the saved-query privacy model.++- [ ] **Step 5: Run all required verification gates**++```bash+buf format -w proto+buf lint proto+(cd proto && buf generate)+gofmt -w backend/api/v1/audit.go backend/api/v1/audit_test.go backend/api/v1/audit_redaction_test.go backend/api/v1/audit_policy_test.go backend/api/v1/auth_service.go backend/tests/login_audit_test.go backend/tests/project_instance_test.go+go test ./backend/api/v1 -count=1+go test -v -count=1 ./backend/tests -run '^(TestAuditLogFormat|TestProjectInstanceCoreBehavior|TestAdminExecuteAuditLog)$' -timeout 10m+golangci-lint run --allow-parallel-runners+go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go+git diff --check+```++Expected: every command PASS. Run `golangci-lint run --allow-parallel-runners` repeatedly until it reports no issues, per repository instructions.++- [ ] **Step 6: Inspect generated and security-sensitive diffs**++```bash+git diff --stat+git diff -- proto/v1/v1 backend/api/v1/audit.go backend/api/v1/auth_service.go backend/api/v1/audit_redaction_test.go backend/api/v1/audit_policy_test.go backend/tests docs/design/v1-api-audit-2026-08.md+```++Confirm no unrelated generated churn, no raw sentinel/credential fixtures outside tests, and no accidental audit annotation on the deliberate exclusions.++- [ ] **Step 7: Commit the policy guard and documentation**++```bash+git add backend/api/v1/audit_policy_test.go docs/design/v1-api-audit-2026-08.md+git commit -m "test: lock v1 API audit policy"+```++---++## Completion Criteria++- Every RPC in the Coverage Decision table has `option (bytebase.v1.audit) = true` in source and generated descriptors.+- `CreateProject`, `UpdateProject`, and the already-annotated `CreateInstance` have end-to-end persistence assertions.+- Project-scoped rows use project parents and canonical resources; workspace-scoped rows use workspace parents.+- All credential/content sentinels are absent from serialized audit payloads, and redaction does not mutate handler messages.+- Deliberate exclusions remain unaudited and are protected by a descriptor policy test.+- Proto format/lint/generation, focused integration tests, backend unit tests, lint, build, and `git diff --check` pass.