adolf/qa/convex-credential-broker/README.md

QA Convex Credential Broker (v1)

Standalone Convex project for shared qa-lab live credentials with lease locking. Keep private operator notes in ~/Projects/manager/docs/, not in public docs.

This broker exposes:

• POST /qa-credentials/v1/acquire
• POST /qa-credentials/v1/payload-chunk
• POST /qa-credentials/v1/heartbeat
• POST /qa-credentials/v1/release
• POST /qa-credentials/v1/admin/add
• POST /qa-credentials/v1/admin/remove
• POST /qa-credentials/v1/admin/list

The implementation matches the contract documented in docs/help/testing.md for --credential-source convex.

Policy baked in

• Pool partitioning: by kind only
• Selection: least-recently-leased (round-robin behavior)
• Secrets: separate maintainer/CI secrets
• Outage behavior: callers fail fast
• Lease event retention: 2 days (hourly cleanup cron)
• Admin event retention: 30 days (hourly cleanup cron)
• App-level encryption: not included in v1

Quick start

1. Create a Convex deployment and authenticate your CLI.
2. From this folder:

cd qa/convex-credential-broker
npm install
npx convex dev

3. Deploy:

npx convex deploy

4. In Convex deployment environment variables, set:

• OPENCLAW_QA_CONVEX_SECRET_MAINTAINER
• OPENCLAW_QA_CONVEX_SECRET_CI

Client URL policy:

• OPENCLAW_QA_CONVEX_SITE_URL must use https:// in normal use.
• Local development may use loopback http:// only when OPENCLAW_QA_ALLOW_INSECURE_HTTP=1.

Manage credentials from qa-lab CLI

Maintainers can manage rows without using the Convex dashboard:

pnpm openclaw qa credentials add \
  --kind telegram \
  --payload-file qa/telegram-credential.json

pnpm openclaw qa credentials add \
  --kind discord \
  --payload-file qa/discord-credential.json

pnpm openclaw qa credentials list --kind telegram

pnpm openclaw qa credentials remove --credential-id <credential-id>

Admin endpoints require OPENCLAW_QA_CONVEX_SECRET_MAINTAINER.

Local request examples

Replace <site-url> with your Convex site URL and <token> with a configured secret.

Acquire:

curl -sS -X POST "<site-url>/qa-credentials/v1/acquire" \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -d '{
    "kind":"telegram",
    "ownerId":"local-dev",
    "actorRole":"maintainer",
    "leaseTtlMs":1200000,
    "heartbeatIntervalMs":30000
  }'

Heartbeat:

curl -sS -X POST "<site-url>/qa-credentials/v1/heartbeat" \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -d '{
    "kind":"telegram",
    "ownerId":"local-dev",
    "actorRole":"maintainer",
    "credentialId":"<credential-id>",
    "leaseToken":"<lease-token>",
    "leaseTtlMs":1200000
  }'

Release:

curl -sS -X POST "<site-url>/qa-credentials/v1/release" \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -d '{
    "kind":"telegram",
    "ownerId":"local-dev",
    "actorRole":"maintainer",
    "credentialId":"<credential-id>",
    "leaseToken":"<lease-token>"
  }'

Admin add (maintainer token only):

curl -sS -X POST "<site-url>/qa-credentials/v1/admin/add" \
  -H "authorization: Bearer <maintainer-token>" \
  -H "content-type: application/json" \
  -d '{
    "kind":"telegram",
    "actorId":"local-maintainer",
    "payload":{
      "groupId":"-100123",
      "driverToken":"driver-token",
      "sutToken":"sut-token"
    }
  }'

For kind: "telegram", broker admin/add validates that payload includes:

• groupId as a numeric chat id string
• non-empty driverToken
• non-empty sutToken

For kind: "telegram-user", broker admin/add validates one exclusive real-user credential for both the TDLib CLI driver and the Telegram Desktop visual witness:

• groupId as a numeric chat id string
• non-empty sutToken
• testerUserId as a numeric Telegram user id string
• non-empty testerUsername
• telegramApiId as a numeric string
• non-empty telegramApiHash
• non-empty tdlibDatabaseEncryptionKey
• non-empty tdlibArchiveBase64
• tdlibArchiveSha256 as a SHA-256 hex string
• non-empty desktopTdataArchiveBase64
• desktopTdataArchiveSha256 as a SHA-256 hex string

Long-running agent sessions should acquire this lease once, keep it for the whole Crabbox review/repro session, then release it from the same session file. Do not run parallel telegram-user jobs against the burner account.

For kind: "discord", broker admin/add validates that payload includes:

• guildId as a Discord snowflake string
• channelId as a Discord snowflake string
• non-empty driverBotToken
• non-empty sutBotToken
• sutApplicationId as a Discord snowflake string

For kind: "whatsapp", broker admin/add validates that payload includes:

• driverPhoneE164 as an E.164 phone number string
• sutPhoneE164 as a distinct E.164 phone number string
• non-empty driverAuthArchiveBase64
• non-empty sutAuthArchiveBase64
• optional groupJid

Other kinds are currently accepted as pass-through payloads. Add broker-side validation before treating a new kind as a hardened shared pool.

Admin list (default redacted):

curl -sS -X POST "<site-url>/qa-credentials/v1/admin/list" \
  -H "authorization: Bearer <maintainer-token>" \
  -H "content-type: application/json" \
  -d '{
    "kind":"telegram",
    "status":"all"
  }'

Admin remove (soft disable, fails when lease is active):

curl -sS -X POST "<site-url>/qa-credentials/v1/admin/remove" \
  -H "authorization: Bearer <maintainer-token>" \
  -H "content-type: application/json" \
  -d '{
    "credentialId":"<credential-id>",
    "actorId":"local-maintainer"
  }'