@astram/guard 0.2.0 → 0.3.0

package/dist/auth/account.controller.d.ts

@@ -0,0 +1,245 @@
+/**
+ * The framework-owned **`/account/*` self-scoped HTTP controller** — the
+ * authenticated user acting on THEIR OWN credential/profile (spec §2). Unlike the
+ * `/auth/*` routes (which run BEFORE a session exists), these routes authenticate
+ * the CALLER first — they resolve the bearer access token to the principal's claims
+ * and operate ONLY on `claims.id`. There is NO `decide()`/object-type authorization
+ * here: "change my own password" has no `typeKey` to gate on (that is the later
+ * permission-management milestone). So the routes are `@Public()` to the
+ * classification guard (not object-gated), but NOT unauthenticated.
+ *
+ * ── AUTH (fail-closed) ── the caller is authenticated by resolving the bearer token
+ *   DIRECTLY via the {@link SessionTokenBinder} (`binder.resolve(token)`), NOT via
+ *   `resolveRequestPrincipal` — because change-password needs the caller's
+ *   `sessionId` (to keep the current session alive while sweeping the others), and
+ *   `resolveRequestPrincipal` collapses the claims down to a `Principal` (dropping
+ *   `sessionId`). No token / no binder / resolve → null → generic 401.
+ *
+ * ── SEAMS (fail-closed → 501) ── the credential read+write goes through the
+ *   consumer-plugged {@link CredentialWriter} (`getPasswordHash` + `setPassword`, now
+ *   password-only); the current-password verify uses the {@link PasswordHasher};
+ *   sessions are swept by the {@link SessionSweeper}. The {@link RecoveryCodeStore},
+ *   the core {@link FactorVerifier} (single-secret TOTP, for per-device code checks),
+ *   the {@link ProfileResolver} (otpauth label), and the {@link MfaDeviceStore}
+ *   (the N-device persistence) are injected here for the multi-device MFA routes. Each
+ *   is `@Optional()`; when a required seam is absent the route returns an honest 501
+ *   (`not_available`) rather than a partial mutation.
+ *
+ *   NOTE: TOTP secrets no longer live on the {@link CredentialWriter} — the
+ *   multi-device MFA model stores every authenticator secret in the `MfaDeviceStore`.
+ *   The old single-secret `mfa/enroll/{begin,confirm}` + `mfa/disable` routes were
+ *   removed; the multi-device `/account/mfa/devices/*` routes replace them.
+ *
+ * ── ROUTES ── `POST /account/change-password` (change own password);
+ *   `PATCH /account/profile` (edit own display name/email → the refreshed display
+ *   profile); the multi-device MFA routes — `GET /account/mfa/devices` (list),
+ *   `POST /account/mfa/devices/begin` (enroll), `POST /account/mfa/devices/confirm`
+ *   (activate + first-device recovery codes), `PATCH /account/mfa/devices/:id/rename`,
+ *   `DELETE /account/mfa/devices/:id` (code-gated), `POST
+ *   /account/mfa/recovery-codes/regenerate` (code-gated).
+ *
+ * ── NO ORACLE ── a wrong current password is an indistinguishable generic 401
+ *   (same body as no-token). We never reveal whether the principal exists, nor which
+ *   check failed. Passwords/hashes are NEVER logged.
+ */
+import type { FactorVerifier, PasswordHasher } from '@astram/core';
+import type { SessionTokenBinder } from '../request-auth/session-token-binder.js';
+import type { CredentialWriter } from './ports/credential-writer.js';
+import type { MfaDevice, MfaDeviceStore } from './ports/mfa-device-store.js';
+import type { CurrentUserProfile, ProfileResolver } from './profile-resolver.js';
+import type { ProfileWriter } from './ports/profile-writer.js';
+import type { RecoveryCodeStore } from './ports/recovery-code-store.js';
+import type { SessionSweeper } from './ports/session-sweeper.js';
+export declare class AccountController {
+    private readonly binder?;
+    private readonly hasher?;
+    private readonly writer?;
+    private readonly sweeper?;
+    private readonly recoveryCodes?;
+    private readonly totpVerifier?;
+    private readonly profileResolver?;
+    private readonly profileWriter?;
+    private readonly mfaDevices?;
+    constructor(binder?: SessionTokenBinder | undefined, hasher?: PasswordHasher | undefined, writer?: (CredentialWriter | null) | undefined, sweeper?: (SessionSweeper | null) | undefined, recoveryCodes?: (RecoveryCodeStore | null) | undefined, totpVerifier?: (FactorVerifier | null) | undefined, profileResolver?: (ProfileResolver | null) | undefined, profileWriter?: (ProfileWriter | null) | undefined, mfaDevices?: (MfaDeviceStore | null) | undefined);
+    /**
+     * Resolve a human-readable otpauth account LABEL for the caller (email, else display
+     * name) via the profile resolver. Best-effort: no resolver / null profile / a thrown
+     * store error → the generic {@link FALLBACK_OTPAUTH_LABEL}. NEVER returns the raw
+     * principal id — the label is shown to the user (in the URI), so a `*_uuid` there
+     * would violate the never-show-UUIDs rule.
+     */
+    private resolveOtpauthLabel;
+    /**
+     * Resolve the bearer token → the caller's FULL claims (id + sessionId), or throw a
+     * generic 401. Uses the binder DIRECTLY (not `resolveRequestPrincipal`) so the
+     * `sessionId` survives — change-password needs it to keep the current session.
+     */
+    private requireClaims;
+    /**
+     * ENFORCED-RE-ENROLL GATE for the self-scoped `/account/*` surface (spec §4.2).
+     *
+     * WHY IT LIVES HERE (not only in the GlobalEnforcementGuard): every `/account/*`
+     * route is `@Public()` to the classification guard (it self-authenticates via
+     * {@link requireClaims}), so the guard's `mustReenroll` gate — which fires only on
+     * `@Classified` routes — NEVER runs on this surface. Without this chokepoint, a
+     * recovery-login (`mustReenroll:true`) session could call the account API DIRECTLY —
+     * e.g. `DELETE /account/mfa/devices/:id` to strip every device + wipe recovery codes
+     * WITHOUT confirming a fresh device — defeating the whole safeguard (spec §4.2:
+     * "calling the API directly cannot bypass it").
+     *
+     * WHY A PER-HANDLER BOOLEAN (not path matching): each handler declares its OWN
+     * re-enroll policy via a literal `allowedDuringReenroll`. This is unambiguous and
+     * cannot be fooled by URL/path normalization — there is no string matching to trick.
+     *
+     * POLICY (spec §4.2 + hardening): a `mustReenroll` session may ADD a device
+     * (`begin`/`confirm`), REGENERATE codes, and READ its devices — but must NOT
+     * REMOVE devices, rename them, change the password, or edit the profile. Removing
+     * devices is the exact attack vector (it strips MFA), so `removeDevice` is BLOCKED.
+     *
+     * A normal (`mustReenroll:false`) session is unaffected — this is a no-op for it.
+     */
+    private enforceReenroll;
+    /**
+     * `POST /account/change-password` — change the AUTHENTICATED caller's own password.
+     * Verifies the current password (read by principal id via the writer seam), writes
+     * the new hash, then revokes the caller's OTHER sessions (keeping the current one
+     * live). Self-scoped: acts only on `claims.id`.
+     *
+     * Outcomes:
+     *   • no/invalid token                       → 401 (generic)
+     *   • newPassword shorter than the minimum   → 422 `{ error: 'weak_password' }`
+     *   • writer/hasher seam absent              → 501 `{ error: 'not_available' }`
+     *   • wrong current password                 → 401 (generic, no write)
+     *   • success                                → 204 (no body)
+     */
+    changePassword(authorization: string | undefined, body: {
+        currentPassword?: string;
+        newPassword?: string;
+    }): Promise<void>;
+    /**
+     * Verify a presented TOTP `code` against a base32 `secret` using the injected core
+     * verifier (the SAME RFC-6238 verifier the login MFA branch uses). Returns the
+     * verdict's `satisfied` boolean; a malformed code/secret → `false` (the verifier
+     * never throws). NEVER logs the code or the secret.
+     */
+    private verifyTotp;
+    /**
+     * `PATCH /account/profile` — edit the AUTHENTICATED caller's OWN display profile
+     * (name and/or email). Self-scoped: acts only on `claims.id`. On success returns the
+     * refreshed {@link CurrentUserProfile} (display names, never UUIDs — the bare `id`
+     * fields are machine-only), so the UI can update the header/user card in place.
+     *
+     * Only the fields actually supplied are written (partial edit). At least one of
+     * `name`/`email` must be present and non-empty; a supplied email must look like an
+     * email. These are semantic validations on the caller's OWN profile (no credential
+     * oracle), so they return precise 422 reasons rather than a generic 4xx.
+     *
+     * Outcomes:
+     *   • no/invalid token                       → 401 (generic)
+     *   • profileWriter seam absent              → 501 `{ error: 'not_available' }`
+     *   • neither name nor email supplied        → 422 `{ error: 'no_changes' }`
+     *   • email supplied but malformed           → 422 `{ error: 'invalid_email' }`
+     *   • success                                → 200 (the refreshed CurrentUserProfile)
+     */
+    updateProfile(authorization: string | undefined, body: {
+        name?: string;
+        email?: string;
+    }): Promise<CurrentUserProfile>;
+    /**
+     * Mint a fresh recovery-code batch, hash each (the SAME Argon2 hasher recovery-code
+     * consume verifies against), and REPLACE the caller's prior codes. Returns the RAW
+     * codes to show the user exactly once. Caller guarantees the recovery store + hasher
+     * are present (checked at the route). NEVER logs the codes or hashes.
+     */
+    private replaceRecoveryCodes;
+    /**
+     * Verify a presented `code` against ANY of the caller's CONFIRMED device secrets
+     * (TOTP), returning true on the first match. Used by remove/regenerate where the
+     * proof may come from any live device (not a specific one). NEVER logs the code.
+     */
+    private verifyAgainstAnyDevice;
+    /**
+     * `GET /account/mfa/devices` — list the caller's CONFIRMED authenticator devices.
+     * `mfaEnabled` reflects whether any confirmed device exists. Pending (unconfirmed)
+     * devices are internal and never surfaced. A device `secret` is never included
+     * (the {@link MfaDevice} display shape omits it).
+     *
+     * Outcomes: no/invalid token → 401; store absent → 501; success → 200
+     * `{ devices: MfaDevice[], mfaEnabled: boolean }`.
+     */
+    listDevices(authorization: string | undefined): Promise<{
+        devices: MfaDevice[];
+        mfaEnabled: boolean;
+    }>;
+    /**
+     * `POST /account/mfa/devices/begin` — start enrolling a NEW authenticator device.
+     * Mints a fresh secret, creates a PENDING device row, and returns the provisioning
+     * material (`otpauthUri` for a QR + `secret` for manual entry). NOT active until
+     * `confirm`. A blank name defaults to `"Authenticator N"` (N = confirmed count + 1).
+     *
+     * Outcomes: 401; store absent → 501; success → 200 `{ deviceId, otpauthUri, secret }`.
+     */
+    beginDevice(authorization: string | undefined, body: {
+        name?: string;
+    }): Promise<{
+        deviceId: string;
+        otpauthUri: string;
+        secret: string;
+    }>;
+    /**
+     * `POST /account/mfa/devices/confirm` — activate a pending device by proving a live
+     * code from it. Loads THAT device's secret (owned + still pending), verifies the
+     * code, and confirms. If this is the caller's FIRST confirmed device, fresh recovery
+     * codes are minted (shown once) and returned; subsequent devices return `{}` and do
+     * NOT touch recovery codes.
+     *
+     * Outcomes: 401; store/recovery/hasher absent → 501; device not pending/owned → 404;
+     * wrong/expired code → 400 (device stays pending); success → 200 `{ recoveryCodes? }`.
+     */
+    confirmDevice(authorization: string | undefined, body: {
+        deviceId?: string;
+        code?: string;
+    }): Promise<{
+        recoveryCodes?: string[];
+    }>;
+    /**
+     * `PATCH /account/mfa/devices/:id/rename` — rename one of the caller's devices.
+     * Cosmetic (renaming a label doesn't weaken 2FA), so it is session-auth only (no
+     * code required), consistent with profile-edit. Trimmed empty name → 422.
+     *
+     * Outcomes: 401; store absent → 501; blank name → 422; not found/owned → 404;
+     * success → 200 `{ device }`.
+     */
+    renameDevice(authorization: string | undefined, id: string, body: {
+        name?: string;
+    }): Promise<{
+        device: MfaDevice;
+    }>;
+    /**
+     * `DELETE /account/mfa/devices/:id` — remove one of the caller's devices. Requires
+     * proof: a live TOTP code from ANY of the caller's remaining confirmed devices, OR a
+     * recovery code — so a hijacked live session can't silently strip MFA. Removing the
+     * LAST device is the "disable MFA" path (authorized by that last device's own code)
+     * and additionally wipes the account's recovery codes.
+     *
+     * Outcomes: 401; store absent → 501; wrong code → 400 (no remove); not found/owned →
+     * 404; success → 204.
+     */
+    removeDevice(authorization: string | undefined, id: string, body: {
+        code?: string;
+    }): Promise<void>;
+    /**
+     * `POST /account/mfa/recovery-codes/regenerate` — mint a fresh recovery-code batch
+     * (replacing the old set). Requires MFA to be enabled (≥1 confirmed device) and proof
+     * — a TOTP from any confirmed device OR an existing recovery code.
+     *
+     * Outcomes: 401; store/recovery/hasher absent → 501; MFA off → 400; wrong code → 400;
+     * success → 200 `{ recoveryCodes }`.
+     */
+    regenerateRecoveryCodes(authorization: string | undefined, body: {
+        code?: string;
+    }): Promise<{
+        recoveryCodes: string[];
+    }>;
+}
+//# sourceMappingURL=account.controller.d.ts.map

package/dist/auth/account.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.controller.d.ts","sourceRoot":"","sources":["../../src/auth/account.controller.ts"],"names":[],"mappings":"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"}