@portaidentity/server 1.7.0

package/dist/auth/interaction-authority.d.ts

@@ -0,0 +1,39 @@
+/** Live OIDC interaction authority used by delayed recovery work and public callbacks. */
+/** Minimal interaction record returned by the provider-owned model. */
+export interface ProviderInteractionRecord {
+    /** Exact public interaction identifier. */
+    readonly uid: string;
+    /** Protocol parameters persisted by the provider. */
+    readonly params: Record<string, unknown>;
+}
+/** Minimal provider model needed to resolve current interaction authority. */
+export interface InteractionAuthorityProvider {
+    /** Provider-owned short-lived interaction model. */
+    readonly Interaction: {
+        /** Find one unexpired interaction by its exact identifier. */
+        find(uid: string): Promise<ProviderInteractionRecord | undefined>;
+    };
+}
+/** Validated live interaction and client identity. */
+export interface LiveInteractionAuthority {
+    /** Exact identifier resolved by the provider. */
+    readonly interactionUid: string;
+    /** Current client identifier persisted in the interaction parameters. */
+    readonly clientId: string;
+}
+/** Resolver shared by artifact issuance and callback verification. */
+export interface InteractionAuthorityResolver {
+    /** Resolve one exact unexpired interaction without trusting transport metadata. */
+    resolve(interactionUid: string): Promise<LiveInteractionAuthority | null>;
+}
+/**
+ * Build a fail-closed resolver over the provider's own interaction model.
+ *
+ * The resolver validates both the requested identifier and the identifier returned by storage.
+ * This prevents malformed or stale transport input from being treated as durable authority.
+ *
+ * @param provider - Provider model which owns interaction lifetime and parameters.
+ * @returns Resolver suitable for both delayed recovery work and public callbacks.
+ */
+export declare function createInteractionAuthorityResolver(provider: InteractionAuthorityProvider): InteractionAuthorityResolver;
+//# sourceMappingURL=interaction-authority.d.ts.map

package/dist/auth/interaction-authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-authority.d.ts","sourceRoot":"","sources":["../../src/auth/interaction-authority.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAO1F,uEAAuE;AACvE,MAAM,WAAW,yBAAyB;IACxC,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,8EAA8E;AAC9E,MAAM,WAAW,4BAA4B;IAC3C,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE;QACpB,8DAA8D;QAC9D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAAC;KACnE,CAAC;CACH;AAED,sDAAsD;AACtD,MAAM,WAAW,wBAAwB;IACvC,iDAAiD;IACjD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,sEAAsE;AACtE,MAAM,WAAW,4BAA4B;IAC3C,mFAAmF;IACnF,OAAO,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAAC;CAC3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,4BAA4B,GACrC,4BAA4B,CAY9B"}

package/dist/auth/interaction-authority.js

@@ -0,0 +1,30 @@
+/** Live OIDC interaction authority used by delayed recovery work and public callbacks. */
+import { z } from 'zod';
+const interactionUidSchema = z.string().min(1).max(128);
+const clientIdSchema = z.string().min(1).max(255);
+/**
+ * Build a fail-closed resolver over the provider's own interaction model.
+ *
+ * The resolver validates both the requested identifier and the identifier returned by storage.
+ * This prevents malformed or stale transport input from being treated as durable authority.
+ *
+ * @param provider - Provider model which owns interaction lifetime and parameters.
+ * @returns Resolver suitable for both delayed recovery work and public callbacks.
+ */
+export function createInteractionAuthorityResolver(provider) {
+    return {
+        async resolve(interactionUid) {
+            const parsedUid = interactionUidSchema.safeParse(interactionUid);
+            if (!parsedUid.success)
+                return null;
+            const interaction = await provider.Interaction.find(parsedUid.data);
+            if (!interaction || interaction.uid !== parsedUid.data)
+                return null;
+            const clientId = clientIdSchema.safeParse(interaction.params.client_id);
+            if (!clientId.success)
+                return null;
+            return { interactionUid: parsedUid.data, clientId: clientId.data };
+        },
+    };
+}
+//# sourceMappingURL=interaction-authority.js.map

package/dist/auth/interaction-authority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-authority.js","sourceRoot":"","sources":["../../src/auth/interaction-authority.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAE1F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACxD,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAiClD;;;;;;;;GAQG;AACH,MAAM,UAAU,kCAAkC,CAChD,QAAsC;IAEtC,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,cAAc;YAC1B,MAAM,SAAS,GAAG,oBAAoB,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;YACjE,IAAI,CAAC,SAAS,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YACpC,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACpE,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,GAAG,KAAK,SAAS,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAC;YACpE,MAAM,QAAQ,GAAG,cAAc,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACxE,IAAI,CAAC,QAAQ,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YACnC,OAAO,EAAE,cAAc,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;QACrE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/auth/magic-link-session.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Magic link session management — cookie + Redis backing store.
+ *
+ * When a magic link is clicked, the handler creates a `_ml_session` cookie
+ * backed by a Redis key containing the authenticated user's ID, the OIDC
+ * interaction UID, and the organization ID. The user is then redirected to
+ * `/interaction/:uid` where `showLogin()` detects the session cookie and
+ * either:
+ *   - **Same browser**: completes the OIDC flow via `interactionFinished()`
+ *   - **Different browser**: shows a "return to original browser" success page
+ *
+ * Properties:
+ *   - **Opaque tokens** — random 32-byte hex strings, no data to decode/forge
+ *   - **Single-use** — Redis keys deleted after first consumption
+ *   - **Short-lived** — 5-minute TTL in Redis
+ *   - **HttpOnly cookies** — prevents JavaScript access (XSS-safe)
+ *   - **SameSite=Lax** — blocks cross-site POST but allows navigational GET
+ *
+ * @example
+ *   // In magic link handler (after token validation):
+ *   await createMagicLinkSession(ctx, { userId, interactionUid, organizationId });
+ *   ctx.redirect(`/interaction/${interactionUid}`);
+ *
+ *   // In login handler (detecting session):
+ *   const session = await consumeMagicLinkSession(ctx, { organizationId, interactionUid });
+ *   if (session) { interactionFinished(ctx, { login: { accountId: session.userId } }); }
+ */
+import type { Context } from 'koa';
+/** Data stored in a magic link session */
+export interface MagicLinkSessionData {
+    /** Authenticated user ID */
+    userId: string;
+    /** OIDC interaction UID (for flow completion) */
+    interactionUid: string;
+    /** Organization ID (for branding on success page) */
+    organizationId: string;
+}
+/** Independently derived authority required to consume one continuation. */
+export interface MagicLinkSessionAuthority {
+    /** Organization recorded by the validated OIDC interaction. */
+    readonly organizationId: string;
+    /** Exact interaction identifier selected by the public route. */
+    readonly interactionUid: string;
+}
+/**
+ * Create a magic link session in Redis and set the `_ml_session` cookie.
+ *
+ * Generates a random session token, stores session data in Redis with a
+ * 5-minute TTL, and sets the token as an HttpOnly cookie.
+ *
+ * @param ctx - Koa context (for cookie setting)
+ * @param data - Session data to store (userId, interactionUid, organizationId)
+ */
+export declare function createMagicLinkSession(ctx: Context, data: MagicLinkSessionData): Promise<void>;
+/**
+ * Consume a magic link session — read and delete in one atomic operation.
+ *
+ * Reads the `_ml_session` cookie and asks Redis to compare the stored tenant and interaction before
+ * deleting the key. The Lua operation makes the compare-and-delete decision single-use under
+ * concurrency. A mismatch preserves both the Redis value and cookie for one legitimate retry.
+ *
+ * @param ctx - Koa context (for cookie reading/clearing)
+ * @param authority - Tenant and interaction independently derived from the live OIDC interaction.
+ * @returns Session data if valid, null otherwise
+ */
+export declare function consumeMagicLinkSession(ctx: Context, authority: MagicLinkSessionAuthority): Promise<MagicLinkSessionData | null>;
+/**
+ * Check if a magic link session cookie is present (without consuming it).
+ * Use this for quick checks before committing to the session flow.
+ *
+ * @param ctx - Koa context
+ * @returns true if the `_ml_session` cookie exists
+ */
+export declare function hasMagicLinkSession(ctx: Context): boolean;
+/**
+ * Clear the magic link session cookie.
+ *
+ * @param ctx - Koa context
+ */
+export declare function clearMagicLinkSessionCookie(ctx: Context): void;
+//# sourceMappingURL=magic-link-session.d.ts.map

package/dist/auth/magic-link-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-link-session.d.ts","sourceRoot":"","sources":["../../src/auth/magic-link-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAuDnC,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,4EAA4E;AAC5E,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAMD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,yBAAyB,GACnC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAgDtC;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAQ9D"}

package/dist/auth/magic-link-session.js

@@ -0,0 +1,183 @@
+/**
+ * Magic link session management — cookie + Redis backing store.
+ *
+ * When a magic link is clicked, the handler creates a `_ml_session` cookie
+ * backed by a Redis key containing the authenticated user's ID, the OIDC
+ * interaction UID, and the organization ID. The user is then redirected to
+ * `/interaction/:uid` where `showLogin()` detects the session cookie and
+ * either:
+ *   - **Same browser**: completes the OIDC flow via `interactionFinished()`
+ *   - **Different browser**: shows a "return to original browser" success page
+ *
+ * Properties:
+ *   - **Opaque tokens** — random 32-byte hex strings, no data to decode/forge
+ *   - **Single-use** — Redis keys deleted after first consumption
+ *   - **Short-lived** — 5-minute TTL in Redis
+ *   - **HttpOnly cookies** — prevents JavaScript access (XSS-safe)
+ *   - **SameSite=Lax** — blocks cross-site POST but allows navigational GET
+ *
+ * @example
+ *   // In magic link handler (after token validation):
+ *   await createMagicLinkSession(ctx, { userId, interactionUid, organizationId });
+ *   ctx.redirect(`/interaction/${interactionUid}`);
+ *
+ *   // In login handler (detecting session):
+ *   const session = await consumeMagicLinkSession(ctx, { organizationId, interactionUid });
+ *   if (session) { interactionFinished(ctx, { login: { accountId: session.userId } }); }
+ */
+import crypto from 'node:crypto';
+import { getRedis } from '../lib/redis.js';
+import { logger } from '../lib/logger.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Cookie name for magic link session token */
+const ML_SESSION_COOKIE = '_ml_session';
+/** Redis key prefix for magic link sessions */
+const ML_SESSION_PREFIX = 'ml_session:';
+/** Session TTL in seconds (5 minutes) */
+const ML_SESSION_TTL = 300;
+/** Session token length in bytes (32 bytes = 64 hex chars) */
+const SESSION_TOKEN_BYTES = 32;
+/**
+ * Atomically compare continuation authority and consume exactly one matching Redis value.
+ *
+ * Mismatches deliberately preserve the key so the legitimate tenant and interaction can retry.
+ * Invalid stored data is not returned and remains bounded by the original five-minute TTL.
+ */
+const CONSUME_MATCHING_SESSION_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then
+  return -2
+end
+local interactionOrganizationId = redis.call('GET', KEYS[2])
+if not interactionOrganizationId or interactionOrganizationId ~= ARGV[1] then
+  return 0
+end
+local decoded, session = pcall(cjson.decode, raw)
+if not decoded or type(session) ~= 'table' then
+  return -1
+end
+if type(session.userId) ~= 'string' or session.userId == '' or
+   type(session.interactionUid) ~= 'string' or session.interactionUid == '' or
+   type(session.organizationId) ~= 'string' or session.organizationId == '' then
+  return -1
+end
+if session.organizationId ~= ARGV[1] or session.interactionUid ~= ARGV[2] then
+  return 0
+end
+redis.call('DEL', KEYS[1])
+return raw
+`;
+// ---------------------------------------------------------------------------
+// Creation
+// ---------------------------------------------------------------------------
+/**
+ * Create a magic link session in Redis and set the `_ml_session` cookie.
+ *
+ * Generates a random session token, stores session data in Redis with a
+ * 5-minute TTL, and sets the token as an HttpOnly cookie.
+ *
+ * @param ctx - Koa context (for cookie setting)
+ * @param data - Session data to store (userId, interactionUid, organizationId)
+ */
+export async function createMagicLinkSession(ctx, data) {
+    const redis = getRedis();
+    const token = crypto.randomBytes(SESSION_TOKEN_BYTES).toString('hex');
+    const key = `${ML_SESSION_PREFIX}${token}`;
+    // Store session data in Redis with TTL
+    await redis.set(key, JSON.stringify(data), 'EX', ML_SESSION_TTL);
+    // Set the cookie — HttpOnly, SameSite=Lax, path=/
+    ctx.cookies.set(ML_SESSION_COOKIE, token, {
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+        secure: ctx.secure,
+        maxAge: ML_SESSION_TTL * 1000, // milliseconds
+        overwrite: true,
+    });
+    logger.debug('Created tenant-bound magic link session');
+}
+// ---------------------------------------------------------------------------
+// Consumption
+// ---------------------------------------------------------------------------
+/**
+ * Consume a magic link session — read and delete in one atomic operation.
+ *
+ * Reads the `_ml_session` cookie and asks Redis to compare the stored tenant and interaction before
+ * deleting the key. The Lua operation makes the compare-and-delete decision single-use under
+ * concurrency. A mismatch preserves both the Redis value and cookie for one legitimate retry.
+ *
+ * @param ctx - Koa context (for cookie reading/clearing)
+ * @param authority - Tenant and interaction independently derived from the live OIDC interaction.
+ * @returns Session data if valid, null otherwise
+ */
+export async function consumeMagicLinkSession(ctx, authority) {
+    const token = ctx.cookies.get(ML_SESSION_COOKIE);
+    if (!token)
+        return null;
+    if (!authority.organizationId || !authority.interactionUid)
+        return null;
+    const redis = getRedis();
+    const key = `${ML_SESSION_PREFIX}${token}`;
+    const interactionAuthorityKey = `interaction:org:${authority.interactionUid}`;
+    const result = await redis.eval(CONSUME_MATCHING_SESSION_SCRIPT, 2, key, interactionAuthorityKey, authority.organizationId, authority.interactionUid);
+    if (result === 0)
+        return null;
+    if (typeof result !== 'string') {
+        clearMagicLinkSessionCookie(ctx);
+        return null;
+    }
+    clearMagicLinkSessionCookie(ctx);
+    try {
+        const parsed = JSON.parse(result);
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            Array.isArray(parsed) ||
+            typeof Reflect.get(parsed, 'userId') !== 'string' ||
+            typeof Reflect.get(parsed, 'interactionUid') !== 'string' ||
+            typeof Reflect.get(parsed, 'organizationId') !== 'string') {
+            logger.warn('Invalid magic link session data');
+            return null;
+        }
+        const data = {
+            userId: Reflect.get(parsed, 'userId'),
+            interactionUid: Reflect.get(parsed, 'interactionUid'),
+            organizationId: Reflect.get(parsed, 'organizationId'),
+        };
+        logger.debug('Consumed tenant-bound magic link session');
+        return data;
+    }
+    catch {
+        logger.warn('Failed to parse magic link session data');
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Cookie Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Check if a magic link session cookie is present (without consuming it).
+ * Use this for quick checks before committing to the session flow.
+ *
+ * @param ctx - Koa context
+ * @returns true if the `_ml_session` cookie exists
+ */
+export function hasMagicLinkSession(ctx) {
+    return !!ctx.cookies.get(ML_SESSION_COOKIE);
+}
+/**
+ * Clear the magic link session cookie.
+ *
+ * @param ctx - Koa context
+ */
+export function clearMagicLinkSessionCookie(ctx) {
+    ctx.cookies.set(ML_SESSION_COOKIE, '', {
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+        maxAge: 0,
+        overwrite: true,
+    });
+}
+//# sourceMappingURL=magic-link-session.js.map

package/dist/auth/magic-link-session.js.map

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

package/dist/auth/rate-limiter.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Redis-based sliding window rate limiter.
+ *
+ * Uses INCR + EXPIRE for atomic counter management. Each action type
+ * (login, magic link, password reset) has its own key format and
+ * configurable limits loaded from system_config with sensible defaults.
+ *
+ * Graceful degradation: if Redis is unavailable, requests are ALLOWED
+ * with a warning log — we never block legitimate users due to Redis failure.
+ *
+ * Key format: ratelimit:{action}:{org_id}:{identifier_hash}
+ *
+ * @example
+ *   const key = buildLoginRateLimitKey(orgId, ip, email);
+ *   const config = await loadLoginRateLimitConfig();
+ *   const result = await checkRateLimit(key, config);
+ *   if (!result.allowed) {
+ *     ctx.status = 429;
+ *     ctx.set('Retry-After', String(result.retryAfter));
+ *   }
+ */
+/** Result of a rate limit check */
+export interface RateLimitResult {
+    /** Whether the request is allowed (within limit) */
+    allowed: boolean;
+    /** Number of remaining requests in this window */
+    remaining: number;
+    /** When the current window expires */
+    resetAt: Date;
+    /** Seconds until the client can retry (0 if allowed) */
+    retryAfter: number;
+}
+/** Configuration for a rate limit rule */
+export interface RateLimitConfig {
+    /** Maximum number of requests allowed in the window */
+    max: number;
+    /** Window duration in seconds */
+    windowSeconds: number;
+}
+/**
+ * Check if a request is within the rate limit for the given key.
+ *
+ * Uses Redis INCR + conditional EXPIRE for atomic counter management:
+ *   1. INCR the key (creates it at 1 if new)
+ *   2. If TTL is -1 (no expiry), set EXPIRE to windowSeconds
+ *   3. Compare count against max — reject if exceeded
+ *
+ * On Redis failure, returns allowed: true with a warning log.
+ *
+ * @param key - Rate limit key (use a build*Key function to construct)
+ * @param config - Rate limit configuration (max requests + window)
+ * @returns Rate limit result with allowed status and metadata
+ */
+export declare function checkRateLimit(key: string, config: RateLimitConfig): Promise<RateLimitResult>;
+/**
+ * Check a security-critical limit without allowing Redis failure to bypass the boundary.
+ *
+ * @param key - Privacy-safe, domain-separated Redis key.
+ * @param config - Maximum attempts and fixed window.
+ * @returns Current limit decision.
+ * @throws When Redis cannot durably increment and expire the attempt counter.
+ */
+export declare function checkRateLimitStrict(key: string, config: RateLimitConfig): Promise<RateLimitResult>;
+/**
+ * Reset the rate limit counter for a key.
+ *
+ * Called after successful authentication to clear the counter,
+ * allowing the user to make fresh attempts if they log out and back in.
+ *
+ * @param key - Rate limit key to reset
+ */
+export declare function resetRateLimit(key: string): Promise<void>;
+/**
+ * Build a rate limit key for login attempts.
+ * Combines IP + email to rate-limit per user per source IP.
+ *
+ * Format: ratelimit:login:{org_id}:{sha256(ip + email)[:16]}
+ *
+ * @param orgId - Organization UUID
+ * @param ip - Client IP address
+ * @param email - Email address being attempted
+ * @returns Rate limit key string
+ */
+export declare function buildLoginRateLimitKey(orgId: string, ip: string, email: string): string;
+/**
+ * Build a rate limit key for magic link requests.
+ * Rate-limits per email to prevent spam.
+ *
+ * Format: ratelimit:magic:{org_id}:{sha256(email)[:16]}
+ *
+ * @param orgId - Organization UUID
+ * @param email - Email address requesting magic link
+ * @returns Rate limit key string
+ */
+export declare function buildMagicLinkRateLimitKey(orgId: string, email: string): string;
+/**
+ * Build the callback-attempt key from tenant, direct socket peer, and protected artifact digest.
+ *
+ * @param orgId - Route organization UUID.
+ * @param socketPeer - Direct TCP peer rather than a caller-controlled forwarding header.
+ * @param artifactDigest - Domain-separated keyed digest of the presented artifact.
+ * @returns Privacy-safe Redis key with isolated tenant, peer, and artifact budgets.
+ */
+export declare function buildMagicLinkCallbackRateLimitKey(orgId: string, socketPeer: string, artifactDigest: string): string;
+/**
+ * Build a rate limit key for password reset requests.
+ * Rate-limits per email to prevent abuse.
+ *
+ * Format: ratelimit:reset:{org_id}:{sha256(email)[:16]}
+ *
+ * @param orgId - Organization UUID
+ * @param email - Email address requesting password reset
+ * @returns Rate limit key string
+ */
+/**
+ * Build a generic rate limit key for custom actions (e.g., 2FA verification, OTP resend).
+ *
+ * @param action - Action identifier (e.g., '2fa_verify', '2fa_resend')
+ * @param orgId - Organization UUID
+ * @param identifier - User-specific identifier (e.g., userId)
+ * @returns Redis key string
+ */
+export declare function buildRateLimitKey(action: string, orgId: string, identifier: string): string;
+export declare function buildPasswordResetRateLimitKey(orgId: string, email: string): string;
+/**
+ * Load login rate limit configuration from system_config.
+ *
+ * @returns Rate limit config with max attempts and window duration
+ */
+export declare function loadLoginRateLimitConfig(): Promise<RateLimitConfig>;
+/**
+ * Load magic link rate limit configuration from system_config.
+ *
+ * @returns Rate limit config with max requests and window duration
+ */
+export declare function loadMagicLinkRateLimitConfig(): Promise<RateLimitConfig>;
+/**
+ * Load password reset rate limit configuration from system_config.
+ *
+ * @returns Rate limit config with max requests and window duration
+ */
+export declare function loadPasswordResetRateLimitConfig(): Promise<RateLimitConfig>;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/auth/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/auth/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAWH,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,OAAO,EAAE,IAAI,CAAC;IACd,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,eAAe,CAAC,CAE1B;AAoBD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/D;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,CAER;AAED;;;;;;;;;GASG;AACH;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnF;AAMD;;;;GAIG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,eAAe,CAAC,CAMzE;AAED;;;;GAIG;AACH,wBAAsB,4BAA4B,IAAI,OAAO,CAAC,eAAe,CAAC,CAM7E;AAED;;;;GAIG;AACH,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,eAAe,CAAC,CAMjF"}