Skip to content

fix(db): keep the server's identity off seed rows read in literal mode - #2306

Merged
cevheri merged 2 commits into
mainfrom
fix/literal-seed-server-identity
Nov 15, 2026
Merged

cevheri merged 2 commits into
mainfrom
fix/literal-seed-server-identity

Conversation

@cevheri

@cevheri cevheri commented Nov 15, 2026

Copy link
Copy Markdown
Member

A seed-file connection read in literal mode (SEED_LITERAL_VALUES) no longer signs in with the server's own Google identity when its password is empty.
BigQuery and Firestore refuse it with a sentence that names the mode, with or without BIGQUERY_SERVER_CREDENTIALS or FIRESTORE_SERVER_CREDENTIALS.
Literal mode exists for a seed file a platform writes from its users' data, so an empty password there is not the operator's grant.
With literal mode off nothing changes.

What changes

  • src/lib/types.ts: LITERAL_SEED_FILE, a symbol key on the footing of TUNNEL_FAR_END, and WithLiteralSeedFile. It is not a field of DatabaseConnection or of the seed schema, so no seed file, request body or stored connection can carry it, and JSON.stringify drops it from every response.
  • src/lib/seed/index.ts: projectOperatorEntries sets the marker beside literal on every operator entry read in literal mode; this is the only place it is set. Discovered and governed rows carry literal but never the marker, and built-in samples carry neither.
  • src/lib/db/auth/server-identity-gate.ts: isServerWritten(connection) is managed === true and no marker. admitServerIdentity takes the record, refuses with unmanaged, then the new literalSeedFile sentence, then withoutOptIn, and reads the opt-in only last.
  • src/lib/db/auth/google/credentials.ts: resolveGoogleCredential takes the connection record (password, managed and the marker) instead of { text, managed }; both providers pass the record they were given.
  • src/lib/db/provider-cache-key.ts: credentialDigest frames the marker last and only when set, so a provider opened with literal mode off is never served to a marked row, and every other key stays byte for byte.
  • BigQuery and Firestore credential policies gain the literalSeedFile sentence.
  • Docs: docs/SEED_CONNECTIONS.md (literal-mode section and the SEED_LITERAL_VALUES row), .env.example (the two server-credential variables and SEED_LITERAL_VALUES), docs/ADDING_A_PROVIDER.md (the gate's three sentences), docs/DB_AUTH.md (root pieces, server identity), docs/providers/bigquery.md and docs/providers/firestore.md (the condition and the quoted sentence), docs/SECURITY.md control 3.40, and docs/BACKLOG.md D85's pinned count (60 to 61, for the new API test's @/lib/auth mock).

User-visible changes

Both apply only to a row of a seed file read in literal mode whose password is empty.

# Change Test
1 With the provider's opt-in exactly "true", the row signed in with the server's own Google identity; it is now refused with the literalSeedFile sentence, and no token is requested and no request is sent tests/api/db/literal-seed-server-identity.test.ts, both providers' credential-policy.test.ts, tests/integration/db/bigquery-provider.test.ts, tests/integration/db/firestore-provider.test.ts
2 With the opt-in off, the refusal was the withoutOptIn sentence; it is now the literalSeedFile sentence tests/api/db/literal-seed-server-identity.test.ts

The new sentences:

  • BigQuery: "BigQuery needs a service-account key or an access token in the password field: the server's own credentials are not used for a connection read from a seed file in literal mode (SEED_LITERAL_VALUES)"
  • Firestore: "Paste a service-account key JSON, an authorized-user JSON or an access token: the server's own Google identity is not used for a connection read from a seed file in literal mode (SEED_LITERAL_VALUES)"

Nothing changes for a seed row read with the mode off, a governed row, a discovered row, a connection a browser sends, or a row with a credential in its password field.
An operator whose literal-mode seed file relied on the server's identity puts a credential on the row, or reads that file with the mode off.

Tests

  • tests/api/db/literal-seed-server-identity.test.ts was written first and was red: through POST /api/db/query, a literal-mode row with an empty password is refused with its sentence and zero requests, with the opt-in on and off; a provider opened with the mode off is not served once the mode is on; the same file with the mode off signs in as the server.
  • server-identity-gate.test.ts: the isServerWritten truth table and the gate's three refusals in order.
  • tests/unit/db/bigquery/credential-policy.test.ts: docs/providers/bigquery.md quotes each of BigQuery's three refusal sentences as the code words it, as Firestore's doc test already does.
  • provider-cache-key.test.ts: the same record with and without the marker gets different keys; a managed: true record without it keeps its key byte for byte.
  • Seed tests (index.test.ts, index-kubernetes-discovery.test.ts, literal-values.test.ts, resolve-connection.test.ts) and visible.test.ts: the marker is on every operator entry in literal mode on both lookups and on the resolved row, and never on a discovered (CapRover, Kubernetes with the review on and off), sample or governed row.

Test plan

bun tests/run-tests.ts <each new or changed test file>
bun tests/run-tests.ts <changed files, every test that reads a touched doc, every test naming providerCacheKey, backlog-structure>   # 373 files, 20639 pass, 1 skip
bun tests/run-tests.ts tests/unit/db/auth tests/unit/db/bigquery tests/unit/db/firestore tests/unit/seed tests/unit/lib/governance tests/unit/lib/db tests/api/db tests/integration/db/bigquery-provider.test.ts tests/integration/db/firestore-provider.test.ts tests/isolated/factory.test.ts   # 148 files pass
bun tests/run-tests.ts tests/security tests/isolated   # 74 files pass
(cd vscode-extension && npm ci --ignore-scripts) && bun run format && bun run lint && bun run typecheck && bun run knip && bun run security:check && bun run readme:check   # green

The full gate and coverage run in CI.

A seed-file connection read in literal mode (SEED_LITERAL_VALUES) no longer signs in with the server's own Google identity when its password is empty.
BigQuery and Firestore refuse it with a new sentence that names the mode, with the server-identity opt-in on or off.
Studio marks such rows with a LITERAL_SEED_FILE symbol key in projectOperatorEntries; isServerWritten is the one definition of a server-written connection and admitServerIdentity reads it.
The marker is framed in the provider cache key, so every other key stays byte for byte.
Review round 1: hold the BigQuery doc's quoted refusals to the code with a
test, say in .env.example and the SEED_LITERAL_VALUES row that a literal-mode
row never uses the server's identity, give ADDING_A_PROVIDER.md the third
gate sentence, and correct comments on built-in samples and on where the
cache key frames the managed part.
@codecov

codecov Bot commented Nov 15, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@sonarqubecloud

Copy link
Copy Markdown

@cevheri
cevheri merged commit 13e4f34 into main Nov 15, 2026
39 checks passed
@cevheri
cevheri deleted the fix/literal-seed-server-identity branch November 15, 2026 05:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant