Repository navigation
feat: add secure SMTP App Password onboarding - #4
Conversation
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
📝 WalkthroughWalkthroughThis PR adds authenticated SMTP email delivery, Gmail App Password onboarding, secure password-store integration, structured partial-delivery results, Telegram delivery notifications, deployment wiring, tests, and operator documentation. ChangesSMTP delivery and secure onboarding
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant Operator
participant smtp-setup.sh
participant smtp-setup.ts
participant pass
participant agent-gate.service
Operator->>smtp-setup.sh: start Gmail setup
smtp-setup.sh->>smtp-setup.ts: run with trusted environment
smtp-setup.ts->>smtp-setup.ts: verify Gmail SMTP credentials
smtp-setup.ts->>pass: store SMTP password
smtp-setup.ts->>agent-gate.service: write provider configuration
smtp-setup.sh->>agent-gate.service: restart and health-check
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@config.example.yaml`:
- Around line 20-29: Update the gmail-smtp example to match the isolated pass
onboarding flow: replace the direct GMAIL_APP_PASSWORD environment reference
with a PASS-based credential reference, or revise the comments to direct
operators to agent-gate-smtp-setup for storing and configuring the App Password.
In `@docs/deployment.md`:
- Around line 161-170: Update the deployment documentation near the gmail-smtp
configuration to explicitly instruct operators to set defaults.provider to
"gmail-smtp" when SMTP delivery is intended, or clearly state that the provider
remains non-default and logging is used otherwise.
In `@src/config.ts`:
- Around line 119-123: Move AGENT_GATE_PASS_BIN resolution and its isAbsolute
validation out of the try block in the placeholder/pass-resolution function,
while keeping only execFileSync and related lookup failures inside the
try/catch. Preserve the specific “Configured pass executable must be absolute”
error so it is not replaced by the generic unresolved-placeholder error.
In `@src/oauth/persist.ts`:
- Around line 89-104: Make the credential write and provider configuration
update reconcilable in the persistence flow containing transactionId,
passReference, and updateProviderConfig. Track whether the password-store write
and configuration commit completed, and on failures reconcile the persisted
configuration before retaining or removing the newly created secret; if the
config already references it, keep the secret, otherwise clean up the
unreferenced credential. Ensure retries do not create unnecessary additional
credential versions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d001685b-e3d4-4658-a50a-b51127f155df
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (27)
.gitignoreREADME.mdconfig.example.yamldocs/credential-handoff.mddocs/deployment.mddocs/hermes.mddocs/smtp-onboarding.mdpackage.jsonscripts/install-production.shscripts/smtp-setup.shsrc/bot.tssrc/config.tssrc/executor.tssrc/oauth/config-writer.tssrc/oauth/persist.tssrc/oauth/secret-store.tssrc/providers/email-smtp.tssrc/providers/index.tssrc/smtp-setup.tssrc/smtp/cli-options.tssrc/smtp/normalize.tssrc/smtp/verify.tstests/executor.test.tstests/oauth-setup.test.tstests/package.test.tstests/smtp-provider.test.tstests/smtp-setup.test.ts
| # Simplest self-hosted Gmail path: create a dedicated Google App Password, | ||
| # store it under agentgate, and use authenticated SMTP over implicit TLS. | ||
| gmail-smtp: | ||
| type: "email-smtp" | ||
| host: "smtp.gmail.com" | ||
| port: 465 | ||
| tlsMode: "implicit" | ||
| username: "[email protected]" | ||
| password: "${GMAIL_APP_PASSWORD}" | ||
| fromAddress: "[email protected]" |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
Align this example with the isolated pass onboarding path.
Line 28 reads the App Password from the service environment, while the comments and onboarding flow promise storage in the isolated password store. Direct operators to agent-gate-smtp-setup or demonstrate a PASS reference instead.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@config.example.yaml` around lines 20 - 29, Update the gmail-smtp example to
match the isolated pass onboarding flow: replace the direct GMAIL_APP_PASSWORD
environment reference with a PASS-based credential reference, or revise the
comments to direct operators to agent-gate-smtp-setup for storing and
configuring the App Password.
| gmail-smtp: | ||
| type: "email-smtp" | ||
| host: "smtp.gmail.com" | ||
| port: 465 | ||
| tlsMode: "implicit" | ||
| username: "[email protected]" | ||
| password: "${PASS:agent-gate/smtp-password-VERSION}" | ||
| fromAddress: "[email protected]" | ||
| displayName: "Your Name" | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Document or select the SMTP default provider.
The manual configuration adds gmail-smtp, but the example’s defaults.provider remains log. An operator following this configuration will not send email through Gmail SMTP; drafts will continue using the log-only provider. Add an explicit instruction to set defaults.provider: "gmail-smtp" when SMTP delivery is intended, or clearly label the provider as non-default.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/deployment.md` around lines 161 - 170, Update the deployment
documentation near the gmail-smtp configuration to explicitly instruct operators
to set defaults.provider to "gmail-smtp" when SMTP delivery is intended, or
clearly state that the provider remains non-default and logging is used
otherwise.
| const passExecutable = process.env.AGENT_GATE_PASS_BIN ?? 'pass'; | ||
| if (process.env.AGENT_GATE_PASS_BIN && !isAbsolute(passExecutable)) { | ||
| throw new Error('Configured pass executable must be absolute'); | ||
| } | ||
| return execFileSync(passExecutable, ['show', key], { encoding: 'utf8' }).trimEnd(); |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Move the AGENT_GATE_PASS_BIN absolute-path check outside the try block.
The check at line 120–122 throws a specific, actionable error ("Configured pass executable must be absolute"), but it's inside the try at line 118, so the catch at line 124 swallows it and replaces it with the generic "Unresolved placeholder: ${PASS:key}". An operator who misconfigures the env var gets a misleading message pointing at the placeholder, not the real cause.
Proposed fix
try {
- const passExecutable = process.env.AGENT_GATE_PASS_BIN ?? 'pass';
- if (process.env.AGENT_GATE_PASS_BIN && !isAbsolute(passExecutable)) {
- throw new Error('Configured pass executable must be absolute');
- }
return execFileSync(passExecutable, ['show', key], { encoding: 'utf8' }).trimEnd();
} catch {
throw new Error(`Unresolved placeholder: \${${name}}`);
}Move the executable resolution and validation above the try:
+ const passExecutable = process.env.AGENT_GATE_PASS_BIN ?? 'pass';
+ if (process.env.AGENT_GATE_PASS_BIN && !isAbsolute(passExecutable)) {
+ throw new Error('Configured pass executable must be absolute');
+ }
try {
return execFileSync(passExecutable, ['show', key], { encoding: 'utf8' }).trimEnd();
} catch {
throw new Error(`Unresolved placeholder: \${${name}}`);
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const passExecutable = process.env.AGENT_GATE_PASS_BIN ?? 'pass'; | |
| if (process.env.AGENT_GATE_PASS_BIN && !isAbsolute(passExecutable)) { | |
| throw new Error('Configured pass executable must be absolute'); | |
| } | |
| return execFileSync(passExecutable, ['show', key], { encoding: 'utf8' }).trimEnd(); | |
| const passExecutable = process.env.AGENT_GATE_PASS_BIN ?? 'pass'; | |
| if (process.env.AGENT_GATE_PASS_BIN && !isAbsolute(passExecutable)) { | |
| throw new Error('Configured pass executable must be absolute'); | |
| } | |
| try { | |
| return execFileSync(passExecutable, ['show', key], { encoding: 'utf8' }).trimEnd(); | |
| } catch { | |
| throw new Error(`Unresolved placeholder: \${${name}}`); | |
| } |
🧰 Tools
🪛 ast-grep (0.44.1)
[warning] Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { execFileSync } from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').
(detect-child-process-typescript)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/config.ts` around lines 119 - 123, Move AGENT_GATE_PASS_BIN resolution
and its isAbsolute validation out of the try block in the
placeholder/pass-resolution function, while keeping only execFileSync and
related lookup failures inside the try/catch. Preserve the specific “Configured
pass executable must be absolute” error so it is not replaced by the generic
unresolved-placeholder error.
| const id = transactionId(); | ||
| const passwordKey = versionedKey('smtp-password', id); | ||
| await options.store.set(passwordKey, options.password); | ||
|
|
||
| const provider: Record<string, unknown> = { | ||
| type: 'email-smtp', | ||
| host: options.host, | ||
| port: options.port, | ||
| tlsMode: options.tlsMode, | ||
| username: options.username, | ||
| password: passReference(passwordKey), | ||
| fromAddress: options.fromAddress | ||
| }; | ||
| if (options.displayName) provider.displayName = options.displayName; | ||
|
|
||
| await updateProviderConfig(options.configPath, options.providerName, provider, options.setAsDefault); |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Make password-store and configuration commits reconcilable.
A failure before updateProviderConfig renames the file leaves an unreferenced App Password; a failure after rename—such as directory fsync—can report failure despite the config already referencing it. Retrying then creates additional credential versions.
Return commit state or reconcile the written config before deciding whether to retain or remove the new secret.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/oauth/persist.ts` around lines 89 - 104, Make the credential write and
provider configuration update reconcilable in the persistence flow containing
transactionId, passReference, and updateProviderConfig. Track whether the
password-store write and configuration commit completed, and on failures
reconcile the persisted configuration before retaining or removing the newly
created secret; if the config already references it, keep the secret, otherwise
clean up the unreferenced credential. Ensure retries do not create unnecessary
additional credential versions.
Summary
email-smtpprovider with mandatory implicit TLS or required STARTTLSagentgatepassstoreagent-gate-smtp-setupbinary and production wrappergmail.sendOAuthSecurity properties
passis resolved before secret entry and forwarded as an absolute pinned executable path${PASS:...}expansion usesexecFileSync, not a shellagentgatefromremains ignored; configuredfromAddressis approved and sentallowFromAlias: trueis explicitly configuredVerification
npm test— 92/92 passingnpm run build— passingagent-gate,agent-gate-oauth, andagent-gate-smtp-setupnpm pack --dry-run— expected 39 files, including SMTP runtime/docsnpm audit --omit=dev— 0 vulnerabilitiesgit diff --check— cleanbash -n scripts/*.sh— cleanReview fixes incorporated
passexecutable.hermes/planning state from production deploymentpartialresult and normalize SMTP usernames before authenticationAGENT_GATE_PASS_BIN; adversarial PATH substitution is covered by testIndependent review
Production verification
/opt/agent-gateinstallation upgraded successfullyagentgatepassword storeagent-gate.servicerestarted healthy with production isolation checks passing