@meith/accounts 0.21.1 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/accounts",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,6 +20,6 @@
   },
   "dependencies": {
     "hash-wasm": "^4.12.0",
-    "@meith/i18n": "0.21.1"
+    "@meith/i18n": "0.22.0"
   }
 }

package/src/federation/catalog.ts

@@ -11,11 +11,6 @@ import type {
 
 export const PROVIDER_KINDS: readonly ProviderKind[] = ['github', 'google', 'oidc']
 
-/**
- * What a link is called when the provider behind it is switched off: the
- * identity stays on the account, so the row still has to say something a
- * member recognises rather than the key it is stored under.
- */
 const PROVIDER_LABELS: Readonly<Record<ProviderKind, string>> = {
   github: 'GitHub',
   google: 'Google',

package/src/member-settings.ts

@@ -32,6 +32,7 @@ export interface MemberSettings {
   readonly website: string | null
   readonly bio: string | null
   readonly displayGroupId: number | null
+  readonly massMailOptInAt: Date | null
 }
 
 export interface MemberGroupChoice {
@@ -67,6 +68,8 @@ export interface MemberSettingsRepository {
     readonly invisible: boolean
   }): Promise<void>
 
+  saveMassMailOptIn(input: { readonly userId: number; readonly optIn: boolean }): Promise<void>
+
   adoptEmail(input: {
     readonly userId: number
     readonly email: string

package/src/ports.ts

@@ -115,27 +115,8 @@ export type RememberRotation =
   | { readonly status: 'reuse'; readonly userId: number; readonly familyId: string }
   | { readonly status: 'invalid' }
 
-/**
- * How long after a remember token is rotated its old value is still honoured.
- *
- * Rotation is single-use, and two requests carrying the same cookie arrive
- * whenever a browser restores several tabs at once, a link is double-clicked, or
- * a prefetch races the navigation that prompted it. Exactly one wins the claim;
- * without this window the others are indistinguishable from a stolen token and
- * cost the member every session they hold. Real theft reuses a token long after
- * the fact, not inside the same breath.
- */
 export const REMEMBER_ROTATION_GRACE_SECONDS = 30
 
-/**
- * Whether a spent remember token is a concurrent request rather than a theft.
- *
- * A revoked family is always theft: the board has already decided about it.
- * Elapsed time is not required to be positive — requests racing each other
- * stamp `now` on the way in, so the one that loses the claim can carry a
- * timestamp from just before the winner wrote `usedAt`, which is the very case
- * this window exists to forgive.
- */
 export function withinRotationGrace(
   row: { readonly usedAt: Date | null; readonly revokedAt: Date | null },
   now: Date,
@@ -187,11 +168,6 @@ export interface CredentialTokenRepository {
     purpose: CredentialPurpose,
     now: Date,
   ): Promise<{ userId: number; payload: string | null } | null>
-  /**
-   * The same lookup without spending the token. A half-finished sign-in has to
-   * survive a mistyped code, so the token that carries it is only consumed once
-   * the second factor is actually satisfied.
-   */
   peek(
     tokenHash: string,
     purpose: CredentialPurpose,
@@ -272,7 +248,6 @@ export interface TwoFactorRepository {
     now: Date
   }): Promise<TwoFactorRecord>
   confirm(userId: number, step: number, now: Date): Promise<boolean>
-  /** False when the step has already been spent, which is a replayed code. */
   spendStep(userId: number, step: number): Promise<boolean>
   remove(userId: number): Promise<boolean>
 }

package/src/service.ts

@@ -25,11 +25,6 @@ export interface IdentityDeps {
   readonly secondFactor?: SecondFactorLookup
 }
 
-/**
- * Whether an account asks for something beyond its password. Kept as a port
- * rather than the whole two-factor service so that the login path cannot reach
- * the secrets it holds — it only ever needs the yes or no.
- */
 export interface SecondFactorLookup {
   isEnrolled(userId: number): Promise<boolean>
 }
@@ -61,11 +56,6 @@ export interface LoginResult {
   readonly expiresAt: Date
 }
 
-/**
- * How long a half-finished sign-in waits for its second factor. Long enough to
- * fetch a phone from another room, short enough that a password proven on a
- * shared machine does not stay proven.
- */
 export const SECOND_FACTOR_TTL_MINUTES = 10
 
 export type LoginOutcome =
@@ -432,11 +422,6 @@ export class IdentityService {
     return { token, expiresAt }
   }
 
-  /**
-   * Who a half-finished sign-in belongs to, without spending it — the code can
-   * be mistyped, and a member who fumbles it should not have to start from
-   * their password again.
-   */
   async pendingSecondFactor(token: string): Promise<PendingSecondFactor | null> {
     const held = await this.store.tokens.peek(await hashToken(token), 'second_factor', this.now())
     if (held === null) return null
@@ -444,7 +429,6 @@ export class IdentityService {
     return { userId: held.userId, remember: held.payload === 'remember' }
   }
 
-  /** Spends the hold and starts the session it was standing in for. */
   async redeemSecondFactor(token: string, context: RequestContext = {}): Promise<LoginResult> {
     const at = this.now()
     const redeemed = await this.store.tokens.consume(await hashToken(token), 'second_factor', at)
@@ -464,11 +448,6 @@ export class IdentityService {
     await this.store.tokens.revokeAllForUser(userId, 'second_factor')
   }
 
-  /**
-   * The second step gets its own counter. The password counters were cleared
-   * when the password proved out, and a six-digit code is worth a million
-   * guesses — far fewer than a password, and so worth far less patience.
-   */
   async assertSecondFactorAttemptsLeft(userId: number): Promise<void> {
     const max = this.config.maxLoginAttempts
     if (max <= 0) return

package/src/totp/secret-box.ts

@@ -8,12 +8,6 @@ const IV_BYTES = 12
 
 const INFO = new TextEncoder().encode('meith/two-factor-secret')
 
-/**
- * The shared secret an authenticator app holds is a password equivalent: with
- * it, anybody can mint that member's codes forever. It is sealed with a key
- * derived from AUTH_SECRET so that a leaked backup, or a read of the table by
- * anything that never had the environment, is not enough on its own.
- */
 export async function sealSecret(plaintext: string, passphrase: string): Promise<string> {
   const key = await deriveKey(passphrase)
   const iv = new Uint8Array(IV_BYTES)

package/src/totp/service.ts

@@ -117,11 +117,6 @@ export class TwoFactorService {
     }
   }
 
-  /**
-   * The enrolment already under way, so the setup screen survives a reload
-   * without minting a second secret — which would strand whatever the member
-   * had already typed into their authenticator app.
-   */
   async pendingEnrolment(userId: number, boardName: string): Promise<Enrolment | null> {
     const record = await this.twoFactor.find(userId)
     if (record === null || record.confirmedAt !== null) return null
@@ -223,11 +218,6 @@ export class TwoFactorService {
   }
 }
 
-/**
- * The yes-or-no the login path needs, straight off the repository. Built here
- * rather than from the whole service so that composing the two does not hand
- * the login path a key it has no use for.
- */
 export function enrolmentLookup(repository: TwoFactorRepository): {
   isEnrolled(userId: number): Promise<boolean>
 } {

package/src/totp/totp.ts

@@ -6,11 +6,6 @@ export const TOTP_DIGITS = 6
 
 export const TOTP_SECRET_BYTES = 20
 
-/**
- * How far either side of now a code is still taken. One step each way covers a
- * device whose clock has drifted and a member who started typing at 29 seconds
- * past; more than that widens the window an intercepted code stays usable in.
- */
 export const TOTP_SKEW_STEPS = 1
 
 export function generateTotpSecret(byteLength = TOTP_SECRET_BYTES): string {
@@ -57,12 +52,6 @@ export interface TotpMatch {
   readonly step: number
 }
 
-/**
- * The step the code belongs to, or null. The step is returned rather than a
- * bare yes so the caller can refuse a code it has already accepted: a code is
- * valid for thirty seconds, and anybody who reads it over a shoulder or off a
- * proxy log has that long to use it first.
- */
 export async function matchTotp(input: {
   readonly secret: string
   readonly code: string

package/src/webauthn/service.ts

@@ -200,12 +200,6 @@ export class PasskeyService {
     return { account, login }
   }
 
-  /**
-   * The same signature check as signing in, against one named account and with
-   * no session at the end of it. A second factor has to prove the device
-   * belongs to the member who has just given their password — accepting any
-   * registered passkey would let anybody past anybody's second step.
-   */
   async proveOwnership(input: {
     readonly userId: number
     readonly credentialId: string