@sylphx/contract 0.2.0

package/dist/endpoints/security.js

@@ -0,0 +1,291 @@
+/**
+ * Security Console endpoints — user security settings UI.
+ * Mirrors `apps/api/src/server/platform/routes/security/*`.
+ *
+ * Production mount: `/security/*`.
+ *
+ * Organised into sub-groups (Wave 3F pattern) so the namespace stays
+ * browsable as it grows:
+ *   • twoFactor  — 2FA + backup codes (7 ops)
+ *   • email      — email change (2 ops)
+ *   • oauth      — OAuth providers (3 ops)
+ *   • password   — password status + set (2 ops)
+ *   • passkeys   — WebAuthn passkeys (5 ops)
+ *   • sessions   — active sessions (4 ops)
+ *   • score      — security score + quick status (2 ops)
+ *   • alerts     — security alerts (4 ops)
+ */
+import { defineEndpoint } from '../endpoint.js';
+import { BackupCodesRegenerateResult, BackupCodesViewResult, EmailChangeConfirmInput, EmailChangeConfirmResult, EmailChangeRequestInput, EmailChangeRequestResult, GetOAuthProvidersResult, GetSecurityAlertsQuery, GetSecurityAlertsResult, GetSessionsResult, MarkAlertReadInput, MarkAlertReadResult, MarkAllAlertsReadResult, OAuthConnectInput, OAuthConnectResult, OAuthDisconnectInput, OAuthDisconnectResult, Passkey, PasskeyDeleteInput, PasskeyDeleteResult, PasskeyListResult, PasskeyRegisterStartResult, PasskeyRegisterVerifyInput, PasskeyRenameInput, PasskeyRenameResult, PasswordStatusResult, RenameSessionInput, RenameSessionResult, RevokeOtherSessionsResult, RevokeSessionInput, RevokeSessionResult, SecurityScoreResult, SecurityStatusQuickResult, SetPasswordInput, SetPasswordResult, TwoFactorDisableResult, TwoFactorSetupResult, TwoFactorStatusResult, TwoFactorVerifyInput, TwoFactorVerifyResult, UnreadAlertCountResult, } from '../schemas/security.js';
+// ── Two-Factor sub-group ───────────────────────────────────────────────────
+const twoFactorEndpoints = {
+    setup: defineEndpoint({
+        method: 'POST',
+        path: '/security/2fa/setup',
+        response: TwoFactorSetupResult,
+        plane: 'management',
+        summary: 'Start 2FA setup (generate TOTP secret + QR code)',
+        tags: ['security'],
+    }),
+    verify: defineEndpoint({
+        method: 'POST',
+        path: '/security/2fa/verify',
+        body: TwoFactorVerifyInput,
+        response: TwoFactorVerifyResult,
+        plane: 'management',
+        summary: 'Verify TOTP code and enable 2FA',
+        tags: ['security'],
+    }),
+    disable: defineEndpoint({
+        method: 'POST',
+        path: '/security/2fa/disable',
+        response: TwoFactorDisableResult,
+        plane: 'management',
+        summary: 'Disable two-factor authentication',
+        tags: ['security'],
+    }),
+    status: defineEndpoint({
+        method: 'GET',
+        path: '/security/2fa/status',
+        response: TwoFactorStatusResult,
+        plane: 'management',
+        summary: 'Get 2FA enabled status + backup codes remaining',
+        tags: ['security'],
+    }),
+    viewBackupCodes: defineEndpoint({
+        method: 'GET',
+        path: '/security/backup-codes',
+        response: BackupCodesViewResult,
+        plane: 'management',
+        summary: 'View remaining unused backup codes',
+        tags: ['security'],
+    }),
+    regenerateBackupCodes: defineEndpoint({
+        method: 'POST',
+        path: '/security/backup-codes/regenerate',
+        response: BackupCodesRegenerateResult,
+        plane: 'management',
+        summary: 'Generate new backup codes, invalidating the previous set',
+        tags: ['security'],
+    }),
+};
+// ── Email Change sub-group ─────────────────────────────────────────────────
+const emailEndpoints = {
+    requestChange: defineEndpoint({
+        method: 'POST',
+        path: '/security/email/change',
+        body: EmailChangeRequestInput,
+        response: EmailChangeRequestResult,
+        plane: 'management',
+        summary: 'Request an email change (sends verification to new address)',
+        tags: ['security'],
+    }),
+    confirmChange: defineEndpoint({
+        method: 'POST',
+        path: '/security/email/confirm',
+        body: EmailChangeConfirmInput,
+        response: EmailChangeConfirmResult,
+        plane: 'management',
+        summary: 'Confirm email change via verification token',
+        tags: ['security'],
+    }),
+};
+// ── OAuth sub-group ────────────────────────────────────────────────────────
+const oauthEndpoints = {
+    getProviders: defineEndpoint({
+        method: 'GET',
+        path: '/security/oauth/providers',
+        response: GetOAuthProvidersResult,
+        plane: 'management',
+        summary: 'List all connected OAuth provider accounts',
+        tags: ['security'],
+    }),
+    connect: defineEndpoint({
+        method: 'POST',
+        path: '/security/oauth/connect',
+        body: OAuthConnectInput,
+        response: OAuthConnectResult,
+        plane: 'management',
+        summary: 'Start OAuth flow to connect a new provider',
+        tags: ['security'],
+    }),
+    disconnect: defineEndpoint({
+        method: 'POST',
+        path: '/security/oauth/disconnect',
+        body: OAuthDisconnectInput,
+        response: OAuthDisconnectResult,
+        plane: 'management',
+        summary: 'Disconnect an OAuth provider account',
+        tags: ['security'],
+    }),
+};
+// ── Password sub-group ─────────────────────────────────────────────────────
+const passwordEndpoints = {
+    status: defineEndpoint({
+        method: 'GET',
+        path: '/security/password/status',
+        response: PasswordStatusResult,
+        plane: 'management',
+        summary: 'Check whether the user has a password set',
+        tags: ['security'],
+    }),
+    set: defineEndpoint({
+        method: 'POST',
+        path: '/security/password/set',
+        body: SetPasswordInput,
+        response: SetPasswordResult,
+        plane: 'management',
+        summary: 'Set a password (for OAuth-only users)',
+        tags: ['security'],
+    }),
+};
+// ── Passkeys sub-group ─────────────────────────────────────────────────────
+const passkeysEndpoints = {
+    list: defineEndpoint({
+        method: 'GET',
+        path: '/security/passkeys',
+        response: PasskeyListResult,
+        plane: 'management',
+        summary: 'List all registered passkeys for the user',
+        tags: ['security'],
+    }),
+    registerStart: defineEndpoint({
+        method: 'POST',
+        path: '/security/passkeys/register/start',
+        response: PasskeyRegisterStartResult,
+        plane: 'management',
+        summary: 'Get WebAuthn options to register a new passkey',
+        tags: ['security'],
+    }),
+    registerVerify: defineEndpoint({
+        method: 'POST',
+        path: '/security/passkeys/register/verify',
+        body: PasskeyRegisterVerifyInput,
+        response: Passkey,
+        plane: 'management',
+        summary: 'Verify WebAuthn response and store the passkey',
+        tags: ['security'],
+    }),
+    rename: defineEndpoint({
+        method: 'POST',
+        path: '/security/passkeys/rename',
+        body: PasskeyRenameInput,
+        response: PasskeyRenameResult,
+        plane: 'management',
+        summary: 'Update the device name of a passkey',
+        tags: ['security'],
+    }),
+    delete: defineEndpoint({
+        method: 'POST',
+        path: '/security/passkeys/delete',
+        body: PasskeyDeleteInput,
+        response: PasskeyDeleteResult,
+        plane: 'management',
+        summary: 'Remove a passkey (MFA-challenge protected)',
+        tags: ['security'],
+    }),
+};
+// ── Sessions sub-group ─────────────────────────────────────────────────────
+const sessionsEndpoints = {
+    list: defineEndpoint({
+        method: 'GET',
+        path: '/security/sessions',
+        response: GetSessionsResult,
+        plane: 'management',
+        summary: 'List all active sessions for the current user',
+        tags: ['security'],
+    }),
+    revoke: defineEndpoint({
+        method: 'POST',
+        path: '/security/sessions/revoke',
+        body: RevokeSessionInput,
+        response: RevokeSessionResult,
+        plane: 'management',
+        summary: 'Revoke a specific session',
+        tags: ['security'],
+    }),
+    revokeOther: defineEndpoint({
+        method: 'POST',
+        path: '/security/sessions/revoke-other',
+        response: RevokeOtherSessionsResult,
+        plane: 'management',
+        summary: 'Revoke all sessions except the current one',
+        tags: ['security'],
+    }),
+    rename: defineEndpoint({
+        method: 'POST',
+        path: '/security/sessions/rename',
+        body: RenameSessionInput,
+        response: RenameSessionResult,
+        plane: 'management',
+        summary: 'Update the name of a session',
+        tags: ['security'],
+    }),
+};
+// ── Score sub-group ────────────────────────────────────────────────────────
+const scoreEndpoints = {
+    getScore: defineEndpoint({
+        method: 'GET',
+        path: '/security/score',
+        response: SecurityScoreResult,
+        plane: 'management',
+        summary: 'Get detailed security score with factors + recommendations',
+        tags: ['security'],
+    }),
+    getStatusQuick: defineEndpoint({
+        method: 'GET',
+        path: '/security/status',
+        response: SecurityStatusQuickResult,
+        plane: 'management',
+        summary: 'Get a quick security overview for the dashboard',
+        tags: ['security'],
+    }),
+};
+// ── Alerts sub-group ───────────────────────────────────────────────────────
+const alertsEndpoints = {
+    list: defineEndpoint({
+        method: 'GET',
+        path: '/security/alerts',
+        query: GetSecurityAlertsQuery,
+        response: GetSecurityAlertsResult,
+        plane: 'management',
+        summary: 'List security alerts',
+        tags: ['security'],
+    }),
+    unreadCount: defineEndpoint({
+        method: 'GET',
+        path: '/security/alerts/unread-count',
+        response: UnreadAlertCountResult,
+        plane: 'management',
+        summary: 'Get number of unread security alerts',
+        tags: ['security'],
+    }),
+    markRead: defineEndpoint({
+        method: 'POST',
+        path: '/security/alerts/mark-read',
+        body: MarkAlertReadInput,
+        response: MarkAlertReadResult,
+        plane: 'management',
+        summary: 'Mark a specific alert as read',
+        tags: ['security'],
+    }),
+    markAllRead: defineEndpoint({
+        method: 'POST',
+        path: '/security/alerts/mark-all-read',
+        response: MarkAllAlertsReadResult,
+        plane: 'management',
+        summary: 'Mark all security alerts as read',
+        tags: ['security'],
+    }),
+};
+// ── Combined namespace ─────────────────────────────────────────────────────
+export const securityEndpoints = {
+    twoFactor: twoFactorEndpoints,
+    email: emailEndpoints,
+    oauth: oauthEndpoints,
+    password: passwordEndpoints,
+    passkeys: passkeysEndpoints,
+    sessions: sessionsEndpoints,
+    score: scoreEndpoints,
+    alerts: alertsEndpoints,
+};