Skip to content

✨ server: add credential salt to account derivation - #1143

Open
aguxez wants to merge 4 commits into
mainfrom
salt
Open

✨ server: add credential salt to account derivation#1143
aguxez wants to merge 4 commits into
mainfrom
salt

Conversation

@aguxez

@aguxez aguxez commented Jul 13, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add a credential salt field to the shared credential contract and persist it in the database with validation
  • Use the salt when deriving account addresses and building account init code across server and client flows
  • Return the salt in auth and passkey responses so downstream consumers stay in sync

Testing

  • Updated API tests to assert salt propagation and default salt behavior
  • Not run (not requested)

Summary by CodeRabbit

  • New Features
    • Added credential salt support across credential creation, address derivation/init-code generation, authentication/registration, passkey metadata, and validation.
    • Authentication and related responses now return the credential salt.
  • Bug Fixes
    • Credential salt is now stored with stricter database constraints to keep address derivation consistent.
    • Updated legacy KYC and activity/account creation flows to use the salted derivation.
    • Expanded persisted-cache invalidation for auth and credential data on release upgrades.
  • Tests
    • Updated auth/kyc/activity tests to verify salt handling in key flows.
  • Chores
    • Improved webhook error reporting for easier troubleshooting.

@changeset-bot

changeset-bot Bot commented Jul 13, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 8002443

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
@exactly/mobile Patch
@exactly/server Patch
@exactly/common Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@coderabbitai

coderabbitai Bot commented Jul 13, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

Walkthrough

Credential salt is added to the shared credential contract, database schema, address derivation, server responses, KYC and activity flows, client account initialization, tests, cache invalidation, and package Changesets.

Changes

Credential salt flow

Layer / File(s) Summary
Salt contract and derivation
common/accountInit.ts, common/deriveAddress.ts, common/validation.ts
Credential validation, address derivation, and account initialization now accept optional salt values and encode them into derived addresses and creation calldata.
Salt storage and server responses
server/database/schema.ts, server/api/auth/..., server/api/passkey.ts, server/utils/createCredential.ts
Credentials store a validated non-null salt, while server authentication, registration, passkey, and credential creation paths select, use, and return it.
Salt-aware KYC and activity flows
server/api/kyc.ts, server/hooks/activity.ts
Legacy KYC checks and activity-triggered account creation now use credential salt.
Client credential propagation
src/utils/server.ts, src/utils/accountClient.ts, src/utils/queryClient.ts
Client credential state, Intercom address derivation, account initialization, and persisted-query invalidation now include salt-related handling.
Flow validation and release metadata
server/test/api/*, server/test/hooks/*, .changeset/*
Authentication, KYC, and activity tests validate salted behavior, and patch Changesets are added for common, server, and mobile packages.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant AuthAPI
  participant CredentialsDB
  participant deriveAddress
  Client->>AuthAPI: Authenticate credential
  AuthAPI->>CredentialsDB: Read credential and salt
  AuthAPI->>deriveAddress: Derive account with factory, x, y, and salt
  deriveAddress-->>AuthAPI: Return derived account address
  AuthAPI-->>Client: Authentication response including salt
Loading

Possibly related issues

Possibly related PRs

  • exactly/exa#637: Both PRs modify legacy KYC detection in server/api/kyc.ts, including isLegacy and factoryData.
  • exactly/exa#682: Both PRs modify version-aware persisted-query invalidation in src/utils/queryClient.ts.

Suggested reviewers: cruzdanilo, nfmelendez, dieguezguille

🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title is concise and clearly describes the main change: adding credential salt to account derivation.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch salt
✨ Simplify code
  • Create PR with simplified code
  • Commit simplified code in branch salt

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@cruzdanilo cruzdanilo changed the title Add credential salt to account derivation ✨ server: add credential salt to account derivation Jul 13, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a credential salt for address derivation and account initialization across the common, server, and mobile packages. It adds a salt column with a hex check constraint to the database schema, updates API endpoints (authentication, registration, and passkey) to retrieve and return the salt, and integrates it into the account client creation process. There are no review comments, so I have no feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7163f50a-fc04-4626-aa68-304a73dc98f3

📥 Commits

Reviewing files that changed from the base of the PR and between f0f3659 and 5aeb5aa.

📒 Files selected for processing (14)
  • .changeset/fuzzy-cows-breathe.md
  • .changeset/neat-eggs-turn.md
  • .changeset/quick-koalas-thread.md
  • common/accountInit.ts
  • common/deriveAddress.ts
  • common/validation.ts
  • server/api/auth/authentication.ts
  • server/api/auth/registration.ts
  • server/api/passkey.ts
  • server/database/schema.ts
  • server/test/api/auth.test.ts
  • server/utils/createCredential.ts
  • src/utils/accountClient.ts
  • src/utils/server.ts

Comment thread server/test/api/auth.test.ts Outdated
@aguxez

aguxez commented Jul 13, 2026

Copy link
Copy Markdown
Contributor Author

close #1143

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0a3fdbee-d558-4037-889e-3f4d6bcfe5b1

📥 Commits

Reviewing files that changed from the base of the PR and between 5aeb5aa and 89dd049.

📒 Files selected for processing (14)
  • .changeset/fuzzy-cows-breathe.md
  • .changeset/neat-eggs-turn.md
  • .changeset/quick-koalas-thread.md
  • common/accountInit.ts
  • common/deriveAddress.ts
  • common/validation.ts
  • server/api/auth/authentication.ts
  • server/api/auth/registration.ts
  • server/api/passkey.ts
  • server/database/schema.ts
  • server/test/api/auth.test.ts
  • server/utils/createCredential.ts
  • src/utils/accountClient.ts
  • src/utils/server.ts

Comment thread server/api/passkey.ts
Comment thread server/database/schema.ts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

♻️ Duplicate comments (3)
server/database/schema.ts (1)

46-46: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Adjust the regex to allow 32-byte salts.

The credentials_salt_hex_check constraint restricts the salt to exactly 40 hex characters (20 bytes), which matches an address size. However, standard CREATE2 salts are encoded as uint256 and are typically 32 bytes (up to 64 hex characters). If the intent is to support generic salts, the regex should allow up to 64 characters to prevent rejecting valid 32-byte salts.

💡 Proposed fix
-    check("credentials_salt_hex_check", sql`${salt} ~ '^0x[0-9a-fA-F]{40}$'`),
+    check("credentials_salt_hex_check", sql`${salt} ~ '^0x[0-9a-fA-F]{1,64}$'`),
server/api/passkey.ts (1)

41-41: 🎯 Functional Correctness | 🔴 Critical | ⚡ Quick win

Parse the salt to ensure proper validation, checksumming, and type safety.

Since factory is explicitly parsed to satisfy the Address brand and apply checksumming, the raw salt strings should be parsed similarly. Passing raw strings risks TypeScript errors (due to a missing Address brand vs string) and bypasses type validation when satisfying schema outputs.

  • server/api/passkey.ts#L41-L41: parse the raw credential.salt from the database (e.g., credential.salt ? parse(Address, credential.salt) : undefined).
  • server/api/auth/authentication.ts#L438-L438: parse the raw credential.salt here as well.
  • server/utils/createCredential.ts#L66-L66: parse zeroAddress to satisfy the Address brand requirements in the returned object.
server/test/api/auth.test.ts (1)

87-87: 📐 Maintainability & Code Quality | 🟡 Minor | 💤 Low value

Add an end-to-end non-default salt test.

All four assertions validate only zeroAddress, so a regression that discards a stored custom salt and returns the default would pass. Add one persisted non-zero salt fixture and assert the exact value through authentication and registration.

  • server/test/api/auth.test.ts#L87-L87: add assertion for a non-default salt fixture here.
  • server/test/api/auth.test.ts#L469-L470: add assertion for a non-default salt fixture here.
  • server/test/api/auth.test.ts#L566-L568: add assertion for a non-default salt fixture here.
  • server/test/api/auth.test.ts#L714-L715: add assertion for a non-default salt fixture here.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b2259f4d-ff24-44e7-a42d-9c8418a611cc

📥 Commits

Reviewing files that changed from the base of the PR and between 89dd049 and 7c849e1.

📒 Files selected for processing (10)
  • .changeset/fuzzy-cows-breathe.md
  • .changeset/neat-eggs-turn.md
  • server/api/auth/authentication.ts
  • server/api/auth/registration.ts
  • server/api/passkey.ts
  • server/database/schema.ts
  • server/test/api/auth.test.ts
  • server/utils/createCredential.ts
  • src/utils/accountClient.ts
  • src/utils/server.ts

@aguxez
aguxez force-pushed the salt branch 2 times, most recently from de531ae to 5a2f223 Compare July 21, 2026 14:39

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
server/utils/createCredential.ts (1)

39-48: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Explicitly persist the salt value in the database.

The salt value is computed and used for address derivation, but it is omitted from the database insert statement. While the database currently defaults to zeroAddress (which happens to match the hardcoded salt value here), omitting it is implicit and fragile. If the salt generation logic ever changes to use a random or custom value, the database will silently store the wrong salt, breaking future authentication.

As per coding guidelines, "prefer explicit over implicit."

💡 Proposed fix
   await database.insert(credentials).values([
     {
       account,
       id: credentialId,
       publicKey,
       factory,
+      salt,
       transports: options?.webauthn?.transports,
       source: options?.source,
     },
   ]);

Source: Coding guidelines


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9df70ae5-2802-40f9-9059-de07cd2d8b2f

📥 Commits

Reviewing files that changed from the base of the PR and between 7c849e1 and 5a2f223.

📒 Files selected for processing (14)
  • .changeset/fuzzy-cows-breathe.md
  • .changeset/neat-eggs-turn.md
  • .changeset/quick-koalas-thread.md
  • common/accountInit.ts
  • common/deriveAddress.ts
  • common/validation.ts
  • server/api/auth/authentication.ts
  • server/api/auth/registration.ts
  • server/api/passkey.ts
  • server/database/schema.ts
  • server/test/api/auth.test.ts
  • server/utils/createCredential.ts
  • src/utils/accountClient.ts
  • src/utils/server.ts

@aguxez
aguxez marked this pull request as ready for review July 21, 2026 15:04

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5a2f223636

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/utils/accountClient.ts
Comment thread server/database/schema.ts

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 67c38eccda

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/utils/queryClient.ts Outdated
Comment thread common/accountInit.ts
Comment thread server/database/schema.ts
@codecov

codecov Bot commented Jul 21, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 85.29412% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.92%. Comparing base (3280674) to head (8002443).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
common/deriveAddress.ts 50.00% 1 Missing ⚠️
server/database/schema.ts 50.00% 1 Missing ⚠️
server/hooks/activity.ts 88.88% 0 Missing and 1 partial ⚠️
src/utils/accountClient.ts 66.66% 1 Missing ⚠️
src/utils/server.ts 75.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1143      +/-   ##
==========================================
+ Coverage   70.74%   70.92%   +0.18%     
==========================================
  Files         262      262              
  Lines       11276    11432     +156     
  Branches     3785     3839      +54     
==========================================
+ Hits         7977     8108     +131     
- Misses       3013     3031      +18     
- Partials      286      293       +7     
Flag Coverage Δ
e2e 70.92% <85.29%> (+0.18%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e33f11998a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread server/database/schema.ts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 8f248439-0c85-46b1-a349-f420e1b4b3bc

📥 Commits

Reviewing files that changed from the base of the PR and between 5a2f223 and e33f119.

📒 Files selected for processing (15)
  • .changeset/fuzzy-cows-breathe.md
  • .changeset/neat-eggs-turn.md
  • server/api/auth/authentication.ts
  • server/api/auth/registration.ts
  • server/api/kyc.ts
  • server/api/passkey.ts
  • server/database/schema.ts
  • server/hooks/activity.ts
  • server/test/api/auth.test.ts
  • server/test/api/kyc.test.ts
  • server/test/hooks/activity.test.ts
  • server/utils/createCredential.ts
  • src/utils/accountClient.ts
  • src/utils/queryClient.ts
  • src/utils/server.ts

Comment thread server/test/hooks/activity.test.ts Outdated
@aguxez
aguxez force-pushed the salt branch 2 times, most recently from 08b9e1f to 079492f Compare July 23, 2026 08:53

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 079492f5db

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/utils/queryClient.ts Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cf35abe92b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread server/database/schema.ts
Comment thread server/test/hooks/activity.test.ts Outdated
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