feat: HOO-770 Check Privy connection and provision wallet

[pashpashkin]

What changed

• Added Privy Install Completion through the internal credential check endpoint.
• Validates stored credentials, deterministically creates or reconciles the first Privy wallet, and atomically activates the Credential and Connection.
• Persists the first wallet as Connection-owned and applies the optional walletLabel.
• Added wallet ownership and failed-secret database constraints.
• Replaced PRIVY_BYOK_PROVISIONING_ENABLED with PRIVY_BYOK_ENABLED.

Why

Pending Privy Connections need a safe completion step that:

• does not create duplicate Provider or SDP wallets during retries;
• activates the Connection only after all required state is consistent;
• does not expose or retain conclusively invalid secret material.

Impact

• Adds an internal dashboard endpoint for completing Privy installation.
• Adds nullable Connection ownership to custody_wallets; existing Config-owned wallets require no backfill.
• Adds no intended runtime behavior change while PRIVY_BYOK_ENABLED is disabled.

Pre-release actions

• Ensure PRIVY_BYOK_ENABLED is disabled or unset in every deployed environment.
• Confirm the schema migration can run within the normal database lock window.
• No data migration or wallet backfill is required.

Post-release actions

• Verify the database migration completed successfully.
• Smoke-test existing Privy Config initialization and wallet provisioning.
• Confirm PRIVY_BYOK_ENABLED remains disabled and monitor API/audit errors.

Result validation

• Full API suite: 170 test files passed
• 1,899 tests passed; 14 skipped
• Focused provisioning and Install Completion suites passed
• API typecheck passed
• Custody package typecheck passed
• Biome checks passed
• Migration ownership and secret constraints covered by tests

Does it affect current flows?

No intended behavioral change while PRIVY_BYOK_ENABLED is disabled.

Existing Config-backed Privy initialization and provisioning remain supported, including the existing env-backed credential path. The migration does not update or delete existing wallet data.

Notes

• PRIVY_BYOK_ENABLED must remain disabled for this release.
• This PR does not enable Connection-backed runtime signing, public wallet selection, additional-wallet/API-key parity, dashboard UI, or Config migration.
• Ambiguous Provider outcomes remain retryable and retain the stored secret; only conclusive credential failures remove it.

[linear]

HOO-770

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sdp-docs	Ready	Preview	Jul 31, 2026 3:11pm
sdp-web	Ready	Preview	Jul 31, 2026 3:11pm

[pashpashkin]

@greptileai review pls

[greptile-apps]

Greptile Summary

Adds Privy BYOK installation completion and deterministic first-wallet provisioning.

• Introduces an authenticated internal credential-check endpoint that validates stored Privy credentials, reconciles or provisions a wallet, and atomically activates the credential and connection.
• Adds connection-owned custody wallets, ownership constraints, failed-secret handling, wallet labels, retry reconciliation, and audit coverage.
• Renames the release flag to PRIVY_BYOK_ENABLED across runtime configuration and deployment examples.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sdp-api/src/services/provider-credential-check.service.ts	Implements gated credential validation, deterministic Privy wallet reconciliation, transactional completion, replay handling, secret cleanup, and auditing.
apps/sdp-api/src/services/stores/provider-credential.store.ts	Adds scoped install-check queries and guarded transactional state transitions for success, terminal failure, and retryable outcomes.
packages/sdp-custody/src/provisioning/index.ts	Extends Privy provisioning with external-ID lookup, idempotent creation, response validation, and ambiguous-outcome reconciliation.
apps/sdp-api/src/db/migrations/postgres/0046_custody_connection_wallet_ownership.sql	Adds connection ownership and default-wallet integrity constraints while permitting terminally failed encrypted credentials to discard ciphertext.
apps/sdp-api/src/services/provider-credential-submission.service.ts	Persists the optional first-wallet label and includes it in submission idempotency fingerprints.
apps/sdp-api/src/lib/feature-flags.ts	Replaces the provisioning-specific Privy BYOK flag with the broader PRIVY_BYOK_ENABLED flag.

Sequence Diagram

sequenceDiagram
  participant Dashboard
  participant API as Internal Custody API
  participant SecretStore
  participant Privy
  participant DB as PostgreSQL

  Dashboard->>API: POST credential/:id/check
  API->>DB: Load pending credential and connection
  API->>SecretStore: Read persisted Privy credential
  API->>Privy: Validate credential
  API->>Privy: Find wallet by deterministic external ID
  alt Wallet absent
    API->>Privy: Create wallet with idempotency key
  end
  API->>DB: Lock project and target rows
  API->>DB: Insert connection-owned wallet
  API->>DB: Activate credential and connection atomically
  API-->>Dashboard: Check result

Loading

_{Reviews (2): Last reviewed commit: "style(custody): apply updated formatting" | Re-trigger Greptile}