Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(external-rest-api): complete verified password recovery

Josué4e335d6a1566
diff --git a/external-rest-api/package-lock.json b/external-rest-api/package-lock.json
index a2e4bc4f5..dd9f4c6a3 100644
--- a/external-rest-api/package-lock.json
+++ b/external-rest-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-external-rest-api",
- "version": "0.1.100",
+ "version": "0.1.101",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-external-rest-api",
- "version": "0.1.100",
+ "version": "0.1.101",
"dependencies": {
"@clerum/jwt-key-policy": "file:../packages/jwt-key-policy",
"cors": "^2.8.5",
diff --git a/external-rest-api/package.json b/external-rest-api/package.json
index 88323b742..4b1a80ddc 100644
--- a/external-rest-api/package.json
+++ b/external-rest-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-external-rest-api",
- "version": "0.1.100",
+ "version": "0.1.101",
"description": "External REST API for profile, team management, and RPC token brokerage",
"main": "dist/main.js",
"engines": {
diff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.ts
index 5bb279b6c..bd16a13e4 100644
--- a/external-rest-api/src/releaseManifest.ts
+++ b/external-rest-api/src/releaseManifest.ts
@@ -8,7 +8,7 @@ export type ReleaseManifest = {
export const releaseManifest: ReleaseManifest = {
releaseId: 'v0.10.0',
- externalRestApiVersion: '0.1.100',
+ externalRestApiVersion: '0.1.101',
rpcProxyVersion: '0.1.126',
desktopVersion: '0.10.0',
minimumDesktopVersion: '0.1.252',
diff --git a/external-rest-api/src/routes/invitations.ts b/external-rest-api/src/routes/invitations.ts
index 825769ed1..71d07f7bd 100644
--- a/external-rest-api/src/routes/invitations.ts
+++ b/external-rest-api/src/routes/invitations.ts
@@ -1,5 +1,6 @@
import { NextFunction, Request, Response, Router } from 'express'
import { verifyToken } from '../authToken.js'
+import { ControlApiError } from '../controlApiClient.js'
import { sendPasswordAuthorityError } from '../http/passwordAdmissionError.js'
import { type AuthedRequest, extractAuthToken, requireAuth } from '../middleware/auth.js'
import { createRateLimiter } from '../middleware/rateLimit.js'
@@ -9,6 +10,7 @@ import {
getInvitationByToken,
listPendingInvitations,
setupInvitationPassword,
+ setupInvitationPasswordWithToken,
} from '../services/invitationsService.js'
import { setProfileSessionCookie } from '../sessionCookie.js'
@@ -46,8 +48,19 @@ function sendAcceptInvitationError(
function sendInvitationPasswordError(
res: Response,
- error: 'not_found' | 'forbidden' | 'not_accepted' | 'not_pending' | 'expired' | 'invalid_password'
+ error:
+ | 'not_found'
+ | 'forbidden'
+ | 'not_accepted'
+ | 'not_pending'
+ | 'expired'
+ | 'invalid_invitation'
+ | 'invalid_password'
): void {
+ if (error === 'invalid_invitation') {
+ res.status(400).json({ error: 'invalid_invitation' })
+ return
+ }
if (error === 'not_found') {
res.status(404).json({ error: 'Invitation not found' })
return
@@ -121,6 +134,17 @@ async function invitationPasswordAuthFromRequest(req: Request): Promise<
}
}
+function isInvalidInvitationProof(error: unknown): boolean {
+ return (
+ error instanceof ControlApiError &&
+ error.status === 400 &&
+ error.body !== null &&
+ typeof error.body === 'object' &&
+ 'error' in error.body &&
+ error.body.error === 'invalid_invitation'
+ )
+}
+
export function createInvitationsRouter(): Router {
const router = Router()
@@ -132,7 +156,16 @@ export function createInvitationsRouter(): Router {
return
}
- const invitation = await getInvitationByToken(token)
+ let invitation: Awaited<ReturnType<typeof getInvitationByToken>>
+ try {
+ invitation = await getInvitationByToken(token)
+ } catch (error) {
+ if (isInvalidInvitationProof(error)) {
+ res.status(400).json({ error: 'invalid_invitation' })
+ return
+ }
+ throw error
+ }
if (!invitation) {
res.status(404).json({ error: 'Invitation not found' })
return
@@ -152,6 +185,44 @@ export function createInvitationsRouter(): Router {
return
}
+ const token = String(req.body?.token || '').trim()
+ const email = String(req.body?.email || '')
+ .trim()
+ .toLowerCase()
+ if (token && email) {
+ let preview: Awaited<ReturnType<typeof getInvitationByToken>>
+ try {
+ preview = await getInvitationByToken(token)
+ } catch (error) {
+ if (isInvalidInvitationProof(error)) {
+ res.status(400).json({ error: 'invalid_invitation' })
+ return
+ }
+ throw error
+ }
+ if (preview?.purpose === 'password_reset') {
+ const result = await setupInvitationPasswordWithToken(
+ token,
+ email,
+ invitationId,
+ password
+ )
+ if (result.error) {
+ sendInvitationPasswordError(res, result.error)
+ return
+ }
+ const sessionToken = result.data?.token
+ if (!result.data || !sessionToken) {
+ res.status(502).json({ error: 'Failed to restore account session' })
+ return
+ }
+ const { token: _sessionToken, ...body } = result.data
+ setProfileSessionCookie(req, res, sessionToken)
+ res.status(200).json(body)
+ return
+ }
+ }
+
const authResult = await invitationPasswordAuthFromRequest(req)
if ('status' in authResult) {
res.status(authResult.status).json(authResult.body)
@@ -166,6 +237,7 @@ export function createInvitationsRouter(): Router {
setProfileSessionCookie(req, res, authResult.auth.sessionToken)
res.status(200).json(result.data)
} catch (error) {
+ if (sendPasswordAuthorityError(error, res)) return
next(error)
}
})
diff --git a/external-rest-api/src/services/invitationsService.ts b/external-rest-api/src/services/invitationsService.ts
index 0d1228914..2575e4435 100644
--- a/external-rest-api/src/services/invitationsService.ts
+++ b/external-rest-api/src/services/invitationsService.ts
@@ -158,3 +158,47 @@ export async function setupInvitationPassword(
return { error: 'invalid_password' }
}
}
+
+export async function setupInvitationPasswordWithToken(
+ token: string,
+ email: string,
+ invitationId: string,
+ password: string
+): Promise<{
+ error?:
+ | 'not_found'
+ | 'forbidden'
+ | 'not_accepted'
+ | 'not_pending'
+ | 'expired'
+ | 'invalid_invitation'
+ | 'invalid_password'
+ data?: InvitationPreview & { passwordUpdated: boolean; token: string }
+}> {
+ try {
+ const data = await controlApiRequest<
+ InvitationPreview & { passwordUpdated: boolean; token: string }
+ >('POST', '/external/invitations/password-token', {
+ body: { email, token, invitationId, password },
+ })
+ return { data }
+ } catch (error) {
+ if (error instanceof ControlApiError && [429, 503].includes(error.status)) throw error
+ if (
+ error instanceof ControlApiError &&
+ error.status === 400 &&
+ error.body &&
+ typeof error.body === 'object' &&
+ 'error' in error.body &&
+ error.body.error === 'invalid_invitation'
+ ) {
+ return { error: 'invalid_invitation' }
+ }
+ const message = error instanceof Error ? error.message : ''
+ if (message.includes('(404)')) return { error: 'not_found' }
+ if (message.includes('(403)')) return { error: 'forbidden' }
+ if (message.includes('(409)')) return { error: 'not_pending' }
+ if (message.includes('(410)')) return { error: 'expired' }
+ return { error: 'invalid_password' }
+ }
+}
diff --git a/external-rest-api/test/routes.invitations.test.ts b/external-rest-api/test/routes.invitations.test.ts
index b112bc927..29cea2db0 100644
--- a/external-rest-api/test/routes.invitations.test.ts
+++ b/external-rest-api/test/routes.invitations.test.ts
@@ -1,6 +1,7 @@
import { beforeEach, describe, expect, it, vi } from 'vitest'
import express from 'express'
import request from 'supertest'
+import { ControlApiError } from '../src/controlApiClient.js'
import { createInvitationsRouter } from '../src/routes/invitations.js'
const authTokenMock = vi.hoisted(() => ({
@@ -13,6 +14,7 @@ const invitationsServiceMock = vi.hoisted(() => ({
getInvitationByToken: vi.fn(),
listPendingInvitations: vi.fn(),
setupInvitationPassword: vi.fn(),
+ setupInvitationPasswordWithToken: vi.fn(),
}))
vi.mock('../src/authToken.js', () => authTokenMock)
@@ -77,6 +79,168 @@ describe('routes/invitations', () => {
)
})
+ it('restores a password-reset session only after the password is updated', async () => {
+ invitationsServiceMock.acceptInvitation.mockResolvedValue({
+ data: {
+ accepted: true,
+ userId: 'user-1',
+ email: '[email protected]',
+ teamId: null,
+ teamName: null,
+ role: 'member',
+ token: 'pre-reset-session-token',
+ },
+ })
+ invitationsServiceMock.setupInvitationPassword.mockResolvedValue({
+ data: { id: 'inv-1', passwordUpdated: true },
+ })
+ invitationsServiceMock.getInvitationByToken.mockResolvedValue({
+ id: 'inv-1',
+ email: '[email protected]',
+ purpose: 'password_reset',
+ status: 'pending',
+ })
+ invitationsServiceMock.setupInvitationPasswordWithToken.mockResolvedValue({
+ data: {
+ id: 'inv-1',
+ email: '[email protected]',
+ purpose: 'password_reset',
+ status: 'accepted',
+ passwordUpdated: true,
+ token: 'post-reset-session-token',
+ },
+ })
+
+ const res = await request(makeApp())
+ .post('/invitations/password')
+ .send({
+ token: 'verified-password-reset-link',
+ email: '[email protected]',
+ invitationId: 'inv-1',
+ password: 'new-password-123',
+ })
+ .expect(200)
+
+ expect(res.body).toEqual({
+ id: 'inv-1',
+ email: '[email protected]',
+ purpose: 'password_reset',
+ status: 'accepted',
+ passwordUpdated: true,
+ })
+ expect(JSON.stringify(res.body)).not.toContain('post-reset-session-token')
+ expect(String(res.headers['set-cookie'])).toContain('profile_session=post-reset-session-token')
+ expect(String(res.headers['set-cookie'])).not.toContain('pre-reset-session-token')
+ expect(invitationsServiceMock.acceptInvitation).not.toHaveBeenCalled()
+ expect(invitationsServiceMock.setupInvitationPassword).not.toHaveBeenCalled()
+ expect(invitationsServiceMock.setupInvitationPasswordWithToken).toHaveBeenCalledWith(
+ 'verified-password-reset-link',
+ 'inv-1',
+ 'new-password-123'
+ )
+ })
+
+ it('preserves only sanitized recovery saturation metadata', async () => {
+ invitationsServiceMock.getInvitationByToken.mockResolvedValue({
+ id: 'inv-1',
+ email: '[email protected]',
+ purpose: 'password_reset',
+ status: 'pending',
+ })
+ invitationsServiceMock.setupInvitationPasswordWithToken.mockRejectedValue(
+ new ControlApiError(
+ 'internal authority detail with no public meaning',
+ 429,
+ { error: 'rate_limited', retryAfterSeconds: 8 },
+ { 'retry-after': '8' }
+ )
+ )
+
+ const res = await request(makeApp())
+ .post('/invitations/password')
+ .send({
+ token: 'verified-password-reset-link',
+ email: '[email protected]',
+ invitationId: 'inv-1',
+ password: 'new-password-123',
+ })
+ .expect(429)
+
+ expect(res.body).toEqual({ error: 'rate_limited', retryAfterSeconds: 8 })
+ expect(res.headers['retry-after']).toBe('8')
+ expect(res.headers['x-ratelimit-limit']).toBeUndefined()
+ expect(res.headers.ratelimit).toBeUndefined()
+ expect(res.headers['set-cookie']).toBeUndefined()
+ })
+
+ it('returns a generic invalid-link response for rejected recovery proof', async () => {
+ invitationsServiceMock.getInvitationByToken.mockResolvedValue({
+ id: 'inv-1',
+ email: '[email protected]',
+ purpose: 'password_reset',
+ status: 'pending',
+ })
+ invitationsServiceMock.setupInvitationPasswordWithToken.mockResolvedValue({
+ error: 'invalid_invitation',
+ })
+
+ const res = await request(makeApp())
+ .post('/invitations/password')
+ .send({
+ token: 'invalid-recovery-proof',
+ email: '[email protected]',
+ invitationId: 'inv-1',
+ password: 'new-password-123',
+ })
+ .expect(400)
+
+ expect(res.body).toEqual({ error: 'invalid_invitation' })
+ expect(res.headers['set-cookie']).toBeUndefined()
+ })
+
+ it('does not expose preview lookup paths or recovery proofs when the signed link is invalid', async () => {
+ invitationsServiceMock.getInvitationByToken.mockRejectedValue(
+ new ControlApiError(
+ 'Control API GET /external/invitations/token/raw-proof failed (400)',
+ 400,
+ { error: 'invalid_invitation' }
+ )
+ )
+
+ const res = await request(makeApp())
+ .post('/invitations/password')
+ .send({
+ token: 'raw-proof',
+ email: '[email protected]',
+ invitationId: 'inv-1',
+ password: 'new-password-123',
+ })
+ .expect(400)
+
+ expect(res.body).toEqual({ error: 'invalid_invitation' })
+ expect(JSON.stringify(res.body)).not.toContain('raw-proof')
+ expect(JSON.stringify(res.body)).not.toContain('/external/invitations/token')
+ expect(res.headers['set-cookie']).toBeUndefined()
+ expect(invitationsServiceMock.setupInvitationPasswordWithToken).not.toHaveBeenCalled()
+ })
+
+ it('sanitizes rejected recovery proofs on the public invitation preview route', async () => {
+ invitationsServiceMock.getInvitationByToken.mockRejectedValue(
+ new ControlApiError(
+ 'Control API GET /external/invitations/token/raw-proof failed (400)',
+ 400,
+ { error: 'invalid_invitation' }
+ )
+ )
+
+ const res = await request(makeApp()).get('/invitations/token/raw-proof').expect(400)
+
+ expect(res.body).toEqual({ error: 'invalid_invitation' })
+ expect(JSON.stringify(res.body)).not.toContain('raw-proof')
+ expect(JSON.stringify(res.body)).not.toContain('/external/invitations/token')
+ })
+
it('falls back to invitation token flow when an old bearer token is invalid', async () => {
authTokenMock.verifyToken.mockReturnValue(null)
invitationsServiceMock.acceptInvitation.mockResolvedValue({
diff --git a/external-rest-api/test/services.invitationsService.recovery.test.ts b/external-rest-api/test/services.invitationsService.recovery.test.ts
new file mode 100644
index 000000000..d16d07c96
--- /dev/null
+++ b/external-rest-api/test/services.invitationsService.recovery.test.ts
@@ -0,0 +1,43 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { setupInvitationPasswordWithToken } from '../src/services/invitationsService.js'
+
+const fetchMock = vi.fn()
+
+describe('setupInvitationPasswordWithToken', () => {
+ beforeEach(() => {
+ fetchMock.mockReset()
+ vi.stubGlobal('fetch', fetchMock)
+ })
+
+ afterEach(() => vi.unstubAllGlobals())
+
+ it('preserves invalid recovery proof as a safe link error', async () => {
+ fetchMock.mockResolvedValue(
+ new Response(JSON.stringify({ error: 'invalid_invitation' }), { status: 400 })
+ )
+
+ await expect(
+ setupInvitationPasswordWithToken(
+ 'synthetic-proof',
+ 'synthetic-row-id',
+ 'synthetic-password'
+ )
+ ).resolves.toEqual({ error: 'invalid_invitation' })
+ })
+
+ it('continues to identify password-policy rejections as invalid passwords', async () => {
+ fetchMock.mockResolvedValue(
+ new Response(JSON.stringify({ error: 'invalid_password' }), { status: 400 })
+ )
+
+ await expect(
+ setupInvitationPasswordWithToken(
+ 'synthetic-proof',
+ 'synthetic-row-id',
+ 'short'
+ )
+ ).resolves.toEqual({ error: 'invalid_password' })
+ })
+})