@voltro/plugin-auth 0.33.0 → 0.34.0

package/dist/{strategy-Ce4FlGi4.js → strategy-Bty6_XUj.js}

@@ -35,9 +35,9 @@ var s = 3e4, c = 1e4, l = (e, t = {}) => {
 	kind: "typeid",
 	prefix: e
 }, e), p = (e = []) => {
-	let t = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map(), i = [], a = [], o = [], s = [], c = [], l = /* @__PURE__ */ new Map();
+	let t = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map(), i = [], a = [], o = [], s = [], c = [], l = [], p = [], m = /* @__PURE__ */ new Map();
 	for (let n of e) t.set(n.id, n), r.set(n.email.toLowerCase(), n);
-	let p = (e, i) => n.gen(function* () {
+	let h = (e, i) => n.gen(function* () {
 		let a = t.get(e);
 		if (!a) return yield* n.fail(new d({ userId: e }));
 		let o = i(a);
@@ -56,24 +56,28 @@ var s = 3e4, c = 1e4, l = (e, t = {}) => {
 			};
 			return t.set(a.id, a), r.set(i, a), a;
 		}),
-		updatePassword: (e, t) => p(e, (e) => ({
+		updatePassword: (e, t) => h(e, (e) => ({
 			...e,
 			passwordHash: t
 		})),
-		setMfaSecret: (e, t) => p(e, (e) => ({
+		setMfaSecret: (e, t) => h(e, (e) => ({
 			...e,
 			mfaSecret: t,
 			mfaEnrolledAt: null
 		})),
-		markMfaEnrolled: (e) => p(e, (e) => ({
+		markMfaEnrolled: (e) => h(e, (e) => ({
 			...e,
 			mfaEnrolledAt: /* @__PURE__ */ new Date()
 		})),
-		clearMfa: (e) => p(e, (e) => ({
+		clearMfa: (e) => h(e, (e) => ({
 			...e,
 			mfaSecret: null,
 			mfaEnrolledAt: null
 		})),
+		markEmailVerified: (e) => h(e, (e) => e.emailVerifiedAt ? e : {
+			...e,
+			emailVerifiedAt: /* @__PURE__ */ new Date()
+		}),
 		listMemberships: (e) => n.sync(() => i.filter((t) => t.userId === e)),
 		addMembership: (e) => n.sync(() => {
 			let t = i.findIndex((t) => t.userId === e.userId && t.tenantId === e.tenantId), n = {
@@ -137,6 +141,74 @@ var s = 3e4, c = 1e4, l = (e, t = {}) => {
 			}, a = o.indexOf(r);
 			return o[a] = i, i;
 		}),
+		latestToken: (e, t) => n.sync(() => {
+			let n = null;
+			for (let r of o) r.userId !== e || r.purpose !== t || (n === null || r.createdAt.getTime() > n.createdAt.getTime()) && (n = r);
+			return n;
+		}),
+		insertInvitation: (e) => n.sync(() => {
+			let t = {
+				...e,
+				email: e.email.toLowerCase(),
+				acceptedAt: null,
+				acceptedByUserId: null,
+				revokedAt: null,
+				revokedByUserId: null,
+				createdAt: /* @__PURE__ */ new Date()
+			};
+			return l.push(t), t;
+		}),
+		findInvitationByHash: (e) => n.sync(() => l.find((t) => t.tokenHash === e) ?? null),
+		acceptInvitation: (e, t, r) => n.sync(() => {
+			let n = l.findIndex((t) => t.tokenHash === e && t.acceptedAt === null && t.revokedAt === null && t.expiresAt.getTime() > r.getTime());
+			if (n < 0) return null;
+			let i = {
+				...l[n],
+				acceptedAt: r,
+				acceptedByUserId: t
+			};
+			return l[n] = i, i;
+		}),
+		revokeInvitation: (e, t, r, i) => n.sync(() => {
+			let n = l.findIndex((n) => n.id === e && n.tenantId === t && n.acceptedAt === null && n.revokedAt === null);
+			return n < 0 ? !1 : (l[n] = {
+				...l[n],
+				revokedAt: i,
+				revokedByUserId: r
+			}, !0);
+		}),
+		listInvitations: (e) => n.sync(() => l.filter((t) => t.tenantId === e).sort((e, t) => t.createdAt.getTime() - e.createdAt.getTime())),
+		countPendingInvitations: (e, t) => n.sync(() => l.filter((n) => n.tenantId === e && n.acceptedAt === null && n.revokedAt === null && n.expiresAt.getTime() > t.getTime()).length),
+		supersedePendingInvitations: (e, t, r, i) => n.sync(() => {
+			let n = t.toLowerCase(), a = 0;
+			for (let t = 0; t < l.length; t++) {
+				let o = l[t];
+				o.tenantId === e && o.email === n && o.acceptedAt === null && o.revokedAt === null && (l[t] = {
+					...o,
+					revokedAt: i,
+					revokedByUserId: r
+				}, a++);
+			}
+			return a;
+		}),
+		insertImpersonationGrant: (e) => n.sync(() => {
+			let t = {
+				...e,
+				startedAt: /* @__PURE__ */ new Date(),
+				endedAt: null,
+				endedReason: null
+			};
+			return p.push(t), t;
+		}),
+		findImpersonationGrantBySession: (e) => n.sync(() => p.find((t) => t.sessionId === e) ?? null),
+		endImpersonationGrant: (e, t, r) => n.sync(() => {
+			let n = p.findIndex((t) => t.sessionId === e && t.endedAt === null);
+			return n < 0 ? !1 : (p[n] = {
+				...p[n],
+				endedAt: r,
+				endedReason: t
+			}, !0);
+		}),
 		replaceRecoveryCodes: (e, t) => n.sync(() => {
 			for (let t = c.length - 1; t >= 0; t--) c[t].userId === e && c.splice(t, 1);
 			let n = /* @__PURE__ */ new Date();
@@ -175,7 +247,7 @@ var s = 3e4, c = 1e4, l = (e, t = {}) => {
 			}, !0);
 		}),
 		isLockedOut: (e, t) => n.sync(() => {
-			let n = l.get(e.toLowerCase());
+			let n = m.get(e.toLowerCase());
 			return n?.lockedUntil != null && t < n.lockedUntil ? {
 				locked: !0,
 				retryAfterSeconds: Math.ceil((n.lockedUntil - t) / 1e3)
@@ -185,15 +257,15 @@ var s = 3e4, c = 1e4, l = (e, t = {}) => {
 			};
 		}),
 		recordLoginFailure: (e, t, r) => n.sync(() => {
-			let n = e.toLowerCase(), i = l.get(n), a = i?.windowStartedAt == null || t - i.windowStartedAt >= r.windowMs, o = i?.lockedUntil != null && t >= i.lockedUntil, s = !i || a || o, c = s ? 1 : i.failedCount + 1, u = s ? t : i.windowStartedAt, d = c >= r.maxAttempts ? t + r.lockMs : null;
-			l.set(n, {
+			let n = e.toLowerCase(), i = m.get(n), a = i?.windowStartedAt == null || t - i.windowStartedAt >= r.windowMs, o = i?.lockedUntil != null && t >= i.lockedUntil, s = !i || a || o, c = s ? 1 : i.failedCount + 1, l = s ? t : i.windowStartedAt, u = c >= r.maxAttempts ? t + r.lockMs : null;
+			m.set(n, {
 				failedCount: c,
-				windowStartedAt: u,
-				lockedUntil: d
+				windowStartedAt: l,
+				lockedUntil: u
 			});
 		}),
 		clearLoginFailures: (e) => n.sync(() => {
-			l.delete(e.toLowerCase());
+			m.delete(e.toLowerCase());
 		})
 	};
 }, m = (e, t = {}) => {

package/dist/strategy.d.ts

@@ -4,6 +4,49 @@ import { SessionSecrets } from '@voltro/protocol/session';
 import { VoidIfEmpty } from 'effect/Types';
 import { YieldableError } from 'effect/Cause';
 
+/** One impersonation grant — "actor is acting as target, on this session,
+ *  until this instant". See `impersonationGrantsTable`. */
+declare interface ImpersonationGrantRecord {
+    readonly id: string;
+    /** The IMPERSONATED session's row id. */
+    readonly sessionId: string;
+    readonly actorUserId: string;
+    /** The impersonator's own session, restored when the grant ends. */
+    readonly actorSessionId: string;
+    readonly targetUserId: string;
+    readonly tenantId: string;
+    readonly reason: string | null;
+    readonly startedAt: Date;
+    readonly expiresAt: Date;
+    readonly endedAt: Date | null;
+    readonly endedReason: string | null;
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+}
+
+/**
+ * A tenant invitation — the grant that turns into a `memberships` row when
+ * redeemed. See `invitationsTable` for why `role` lives here and not in the
+ * accept request.
+ */
+declare interface InvitationRecord {
+    readonly id: string;
+    /** SHA-256 hex of the plaintext token. The plaintext lives only in the email. */
+    readonly tokenHash: string;
+    /** The invited address, lower-cased. */
+    readonly email: string;
+    readonly tenantId: string;
+    /** The role the membership is created with. Chosen by the INVITER. */
+    readonly role: string;
+    readonly invitedByUserId: string;
+    readonly expiresAt: Date;
+    readonly acceptedAt: Date | null;
+    readonly acceptedByUserId: string | null;
+    readonly revokedAt: Date | null;
+    readonly revokedByUserId: string | null;
+    readonly createdAt: Date;
+}
+
 /**
  * Brute-force lockout policy, resolved from `AuthConfig.lockout` and passed
  * INTO the store on each failure so the store itself stays policy-free.
@@ -90,7 +133,7 @@ declare interface SessionRevocationOptions {
  *  or the keyed `{ current, previous? }` rotation set. */
 declare type SessionSecretInput = string | SessionSecrets;
 
-declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending';
+declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending' | 'email-verify';
 
 /** A single-use, hashed, expiring token (magic-link / password-reset). */
 declare interface TokenRecord {
@@ -150,6 +193,18 @@ declare interface UserRecord {
      *  verify). Distinct from the secret being set — a half-completed
      *  enrolment leaves `mfaSecret` populated but this null. */
     readonly mfaEnrolledAt?: Date | null;
+    /**
+     * When this address was PROVEN to reach its owner — by redeeming a
+     * verification link, a magic link, or a password-reset link. `null` /
+     * absent = unproven.
+     *
+     * A store whose backing table predates the `emailVerifiedAt` column simply
+     * leaves it undefined, which reads as unverified — and that is why
+     * `emailVerification.policy` defaults to `'off'`: under any stricter
+     * default, "the column is not there yet" and "this user never confirmed"
+     * would both refuse the login.
+     */
+    readonly emailVerifiedAt?: Date | null;
     /** Optional lifecycle flag read by post-authentication subject guards.
      *  Set (a `Date`) means the account is DEACTIVATED — `@voltro/plugin-
      *  deactivation`'s `deactivationGuard()` vetoes login when it's non-null.
@@ -178,6 +233,15 @@ declare interface UserStore {
     /** Wipe the secret + enrolledAt. Used by /account/security's
      *  "remove MFA" action. */
     readonly clearMfa: (userId: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+    /**
+     * Stamp `emailVerifiedAt` — the address has been proven.
+     *
+     * IDEMPOTENT and non-regressing: a user already verified keeps their
+     * ORIGINAL timestamp. "When was this address first proven" is the question
+     * the column answers, and re-stamping it on every later magic-link login
+     * would quietly turn it into "when did they last click something".
+     */
+    readonly markEmailVerified: (userId: string) => Effect.Effect<UserRecord, UserNotFoundError>;
     /** Every tenant the user belongs to. */
     readonly listMemberships: (userId: string) => Effect.Effect<ReadonlyArray<MembershipRecord>>;
     /** Idempotent grant: inserts the [userId, tenantId] membership or
@@ -215,6 +279,52 @@ declare interface UserStore {
      *  already consumed — and marks it consumed in the same step. Returns
      *  null otherwise (single-use guard). */
     readonly consumeToken: (tokenHash: string, purpose: TokenPurpose) => Effect.Effect<TokenRecord | null>;
+    /**
+     * The most recently CREATED token of this purpose for the user, consumed or
+     * not — or null when there is none.
+     *
+     * Exists for the resend cooldown, which is the only bound on an endpoint
+     * that sends mail to an address supplied by an unauthenticated caller. Note
+     * it deliberately does NOT filter on `consumedAt`: the cost being rate-
+     * limited is the EMAIL, and a token that was minted and then redeemed cost
+     * exactly as much to send as one still pending.
+     */
+    readonly latestToken: (userId: string, purpose: TokenPurpose) => Effect.Effect<TokenRecord | null>;
+    /** Persist an invitation (token already hashed). */
+    readonly insertInvitation: (invitation: Omit<InvitationRecord, 'acceptedAt' | 'acceptedByUserId' | 'revokedAt' | 'revokedByUserId' | 'createdAt'>) => Effect.Effect<InvitationRecord>;
+    /** Look an invitation up by token hash WITHOUT redeeming it — the read the
+     *  "what am I being invited to" preview needs. Returns the row whatever its
+     *  state; the caller decides what an expired or revoked one means. */
+    readonly findInvitationByHash: (tokenHash: string) => Effect.Effect<InvitationRecord | null>;
+    /**
+     * Atomically redeem an invitation: returns the row only when it exists, is
+     * unaccepted, unrevoked and unexpired — and stamps `acceptedAt` +
+     * `acceptedByUserId` in the same step. Null otherwise.
+     *
+     * The single-use guard, and it has to be ONE statement: two clicks on the
+     * same emailed link race, and a read-then-write would let both through and
+     * write the membership twice.
+     */
+    readonly acceptInvitation: (tokenHash: string, acceptedByUserId: string, now: Date) => Effect.Effect<InvitationRecord | null>;
+    /** Withdraw a PENDING invitation, scoped to its tenant so an admin of one
+     *  tenant cannot revoke another's by id. Returns whether a row changed. */
+    readonly revokeInvitation: (invitationId: string, tenantId: string, revokedByUserId: string, now: Date) => Effect.Effect<boolean>;
+    /** Every invitation for a tenant, newest first. The admin list. */
+    readonly listInvitations: (tenantId: string) => Effect.Effect<ReadonlyArray<InvitationRecord>>;
+    /** How many invitations for this tenant are still redeemable — the bound
+     *  `maxPending` enforces. */
+    readonly countPendingInvitations: (tenantId: string, now: Date) => Effect.Effect<number>;
+    /** Revoke every pending invitation for (tenant, email). Called before
+     *  issuing a fresh one so re-inviting supersedes rather than accumulates —
+     *  otherwise every resend leaves a live token behind. Returns the count. */
+    readonly supersedePendingInvitations: (tenantId: string, email: string, revokedByUserId: string, now: Date) => Effect.Effect<number>;
+    /** Record an impersonation grant when the impersonated session is minted. */
+    readonly insertImpersonationGrant: (grant: Omit<ImpersonationGrantRecord, 'startedAt' | 'endedAt' | 'endedReason'>) => Effect.Effect<ImpersonationGrantRecord>;
+    /** The grant for an impersonated session, or null. The stop path's lookup. */
+    readonly findImpersonationGrantBySession: (sessionId: string) => Effect.Effect<ImpersonationGrantRecord | null>;
+    /** Close a grant. Only an OPEN grant is closed (`endedAt IS NULL`), so a
+     *  double stop is a no-op rather than a rewritten end time. */
+    readonly endImpersonationGrant: (sessionId: string, endedReason: string, now: Date) => Effect.Effect<boolean>;
     /** Replace the user's recovery codes with a fresh (already hashed) set.
      *  Called at enrolment / regeneration — wipes any prior codes so the
      *  displayed set is the only valid one. */

package/dist/strategy.js

@@ -1,3 +1,3 @@
 import "./session.js";
-import { t as e } from "./strategy-Ce4FlGi4.js";
+import { t as e } from "./strategy-Bty6_XUj.js";
 export { e as voltroPasswordStrategy };

package/dist/tokens.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Default email-verification lifetime — 24 hours.
+ *
+ * Longer than the other two on purpose, and the asymmetry is the point. A
+ * magic link and a reset link are CREDENTIALS: whoever holds one signs in, so
+ * a short fuse is worth the friction of asking for another. A verification
+ * link grants nothing — redeeming it only asserts that the address reaches its
+ * owner — so the cost of a short lifetime is all friction and no security, paid
+ * by exactly the users who check mail once a day.
+ */
+export declare const EMAIL_VERIFY_TTL_S: number;
+
 /** Hash a plaintext token for storage / lookup. SHA-256 is sufficient —
  *  the token is high-entropy (32 random bytes), so there's no
  *  brute-force surface that would need a slow KDF. */
@@ -6,6 +18,16 @@ export declare const hashToken: (plaintext: string) => string;
 /** Default magic-link lifetime — short, since it's an inbox round-trip. */
 export declare const MAGIC_LINK_TTL_S: number;
 
+/** Lifetime of the short-lived MFA pending token (the second-factor
+ *  challenge). Long enough for the user to fetch a TOTP code, short enough
+ *  that a leaked challenge is near-useless.
+ *
+ *  Lives HERE rather than beside the MFA handler that mints it, because the
+ *  default-TTL table below has to be exhaustive over `TokenPurpose` and a
+ *  constant imported from `handlers.ts` would be a cycle. `handlers.ts`
+ *  re-exports it, so the public spelling is unchanged. */
+export declare const MFA_PENDING_TTL_S: number;
+
 export declare interface MintedToken {
     /** The plaintext — put this in the emailed link. Never stored. */
     readonly token: string;
@@ -16,6 +38,19 @@ export declare interface MintedToken {
     readonly purpose: TokenPurpose;
 }
 
+/**
+ * Mint a fresh single-use secret with NO purpose attached — 32 CSPRNG bytes,
+ * its SHA-256, and an expiry.
+ *
+ * Exists for the credentials that are single-use, hashed and expiring but do
+ * NOT live in `authTokens`: a tenant invitation carries its own row (with an
+ * address, a tenant and a role), so it has no `TokenPurpose` to name. Reaching
+ * for `mintToken('magic-link', …)` just to obtain the bytes would file an
+ * invitation under a purpose it does not have, in a type everything else reads
+ * as authoritative.
+ */
+export declare const mintSecret: (ttlSeconds: number) => Omit<MintedToken, "purpose">;
+
 /**
  * Mint a fresh single-use token. The caller persists `{ tokenHash,
  * userId, purpose, expiresAt }` via `UserStore.insertToken` and emails
@@ -26,6 +61,6 @@ export declare const mintToken: (purpose: TokenPurpose, ttlSeconds?: number) =>
 /** Default password-reset lifetime — a bit longer. */
 export declare const PASSWORD_RESET_TTL_S: number;
 
-declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending';
+declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending' | 'email-verify';
 
 export { }

package/dist/tokens.js

@@ -1,13 +1,20 @@
 import { createHash as e, randomBytes as t } from "node:crypto";
 //#region src/tokens.ts
-var n = 900, r = 3600, i = (e) => e.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""), a = (t) => e("sha256").update(t).digest("hex"), o = (e, n) => {
-	let r = i(t(32)), o = n ?? (e === "magic-link" ? 900 : 3600);
+var n = 900, r = 3600, i = 1440 * 60, a = 300, o = {
+	"magic-link": 900,
+	"password-reset": r,
+	"mfa-pending": 300,
+	"email-verify": i
+}, s = (e) => e.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""), c = (t) => e("sha256").update(t).digest("hex"), l = (e) => {
+	let n = s(t(32));
 	return {
-		token: r,
-		tokenHash: a(r),
-		expiresAt: new Date(Date.now() + o * 1e3),
-		purpose: e
+		token: n,
+		tokenHash: c(n),
+		expiresAt: new Date(Date.now() + e * 1e3)
 	};
-};
+}, u = (e, t) => ({
+	...l(t ?? o[e]),
+	purpose: e
+});
 //#endregion
-export { n as MAGIC_LINK_TTL_S, r as PASSWORD_RESET_TTL_S, a as hashToken, o as mintToken };
+export { i as EMAIL_VERIFY_TTL_S, n as MAGIC_LINK_TTL_S, a as MFA_PENDING_TTL_S, r as PASSWORD_RESET_TTL_S, c as hashToken, l as mintSecret, u as mintToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-auth",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Authentication primitives: password hashing, session creation, schema mixin + tables. Pairs with the `auth` app template for the UI; both independently usable. Server-side only (uses node:crypto).",
   "keywords": [
     "voltro",
@@ -79,8 +79,8 @@
   },
   "dependencies": {
     "@effect/sql": "^0.52.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/protocol": "0.33.0"
+    "@voltro/database": "0.34.0",
+    "@voltro/protocol": "0.34.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0",