@pondoknusa/telegram-2fa 6.0.0 → 6.0.1

package/README.md

@@ -0,0 +1,89 @@
+# @pondoknusa/telegram-2fa
+
+Two-factor authentication for Pondoknusa that delivers one-time codes to a user's Telegram chat
+and enforces a verified session on protected routes.
+
+Passwords get phished; a code sent to a chat the attacker doesn't control does not. This package
+sends a short-lived, hashed verification code over the bot from `@pondoknusa/telegram`, verifies
+submissions in constant time, and exposes middleware that gates routes on a session marked
+2FA-verified. It is its own package because it depends on both the auth stack and the Telegram
+bot, neither of which every app needs together.
+
+> Part of the [Pondoknusa](https://pondoknusa.dev) framework — a TypeScript-native full-stack
+> framework built on standard Web APIs. Requires **Node.js ≥ 26**.
+
+## Install
+
+```bash
+npm install @pondoknusa/telegram-2fa
+```
+
+`@pondoknusa/telegram` (the bot) and `@pondoknusa/auth` are installed automatically as
+dependencies of this package.
+
+## Quick start
+
+Register the providers, then send and verify a code. Config lives in `config/telegram-2fa.ts`
+(`Telegram2FaConfig`): `code_length`, `code_ttl_seconds`, `max_attempts`, `session_key`, and more.
+
+```typescript
+// src/main.ts
+import { TelegramServiceProvider } from '@pondoknusa/telegram';
+import { Telegram2FaServiceProvider, TwoFactor } from '@pondoknusa/telegram-2fa';
+
+app.register(TelegramServiceProvider);
+app.register(Telegram2FaServiceProvider);
+await app.boot();
+TwoFactor.setApplication(app);
+```
+
+```typescript
+import { TwoFactor } from '@pondoknusa/telegram-2fa';
+
+// 1. Enabling — send a one-time code to the user's Telegram chat.
+await TwoFactor.manager().send(user); // stores a SHA-256 hash in the cache under the TTL
+
+// 2. Verifying — check the code the user submits.
+const result = await TwoFactor.manager().verify(user, submittedCode);
+
+if (result.success) {
+  TwoFactor.markVerified(request); // stamp the session as 2FA-verified
+}
+```
+
+`verify()` returns `{ success, reason? }`, where a failure is `'expired'`, `'max_attempts'`, or
+`'invalid'`. Call `TwoFactor.manager().invalidate(user)` to drop any pending code, and
+`TwoFactor.isVerified(request)` to read the current session state.
+
+### Protecting routes
+
+```typescript
+import { createRequireTwoFactorMiddleware } from '@pondoknusa/telegram-2fa';
+
+Route.middleware('2fa', createRequireTwoFactorMiddleware()).get('/admin', handler);
+```
+
+The middleware returns `403` unless the session key (default `telegram_2fa_verified`) is present
+and within `session_ttl_seconds`. Pass `skipSafeMethods: true` to challenge only mutating
+requests, or `onChallengeRequired` to supply your own response. The manager reads a
+`telegram_chat_id` model attribute, then falls back to `routeNotificationForTelegram()`; override
+`resolveChatIdResolver()` in a `Telegram2FaServiceProvider` subclass to customize it.
+
+## Related packages
+
+- [`@pondoknusa/telegram`](https://www.npmjs.com/package/@pondoknusa/telegram) — the bot client
+  that delivers the codes.
+- [`@pondoknusa/auth`](https://www.npmjs.com/package/@pondoknusa/auth) — sessions and the
+  authenticated user the challenge runs against.
+- [`@pondoknusa/cache`](https://www.npmjs.com/package/@pondoknusa/cache) — stores the hashed
+  codes with a TTL.
+- [`@pondoknusa/core`](https://www.npmjs.com/package/@pondoknusa/core) — service providers, the
+  container, and the `TwoFactor` facade.
+
+## Documentation
+
+- [Authentication guide](https://pondoknusa.dev/guide/auth)
+- [Package reference](https://pondoknusa.dev/reference/generated/packages/telegram-2fa)
+- [Source](https://git.simonharms.com/thesimonharms/pondoknusa/src/branch/main/packages/telegram-2fa)
+
+MIT © Pondoknusa Contributors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pondoknusa/telegram-2fa",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,13 +15,13 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pondoknusa/auth": "6.0.0",
-    "@pondoknusa/cache": "6.0.0",
-    "@pondoknusa/config": "6.0.0",
-    "@pondoknusa/core": "6.0.0",
-    "@pondoknusa/http": "6.0.0",
-    "@pondoknusa/support": "6.0.0",
-    "@pondoknusa/telegram": "6.0.0"
+    "@pondoknusa/auth": "6.0.1",
+    "@pondoknusa/cache": "6.0.1",
+    "@pondoknusa/config": "6.0.1",
+    "@pondoknusa/core": "6.0.1",
+    "@pondoknusa/http": "6.0.1",
+    "@pondoknusa/support": "6.0.1",
+    "@pondoknusa/telegram": "6.0.1"
   },
   "files": [
     "dist"