@lastshotlabs/bunshot 0.0.21 → 0.0.27

package/dist/lib/pagination.d.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import type { ZodType } from "zod";
+export type { PaginationOpts, PaginatedResult } from "./groups";
+export interface OffsetParamDefaults {
+    /** Default: 50 */
+    limit?: number;
+    /** Default: 200 */
+    maxLimit?: number;
+    /** Default: 0 */
+    offset?: number;
+}
+export interface ParsedOffsetParams {
+    limit: number;
+    offset: number;
+}
+/**
+ * Zod schema for offset pagination query params.
+ * Fields are `z.string().optional()` — matches the existing query param
+ * convention. Parse the values with `parseOffsetParams`.
+ *
+ * @example
+ * createRoute({ ..., request: { query: offsetParams({ limit: 20 }) }, ... })
+ */
+export declare function offsetParams(defaults?: OffsetParamDefaults): z.ZodObject<{
+    limit: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Parses raw string query values into clamped integers.
+ * - NaN (non-numeric strings) falls back to defaults
+ * - limit clamped to [1, maxLimit]
+ * - offset clamped to [0, ∞)
+ *
+ * @example
+ * const { limit, offset } = parseOffsetParams(c.req.query(), { maxLimit: 100 });
+ */
+export declare function parseOffsetParams(raw: {
+    limit?: string;
+    offset?: string;
+}, defaults?: OffsetParamDefaults): ParsedOffsetParams;
+/**
+ * Zod schema factory for paginated offset responses.
+ * Wraps `itemSchema` in `{ items, total, limit, offset }` and registers
+ * the result as a named OpenAPI component.
+ *
+ * Throws if `name` was previously registered to a different schema instance.
+ * Calling with the same `name` + `schema` pair is idempotent.
+ *
+ * @example
+ * const PaginatedUsersResponse = paginatedResponse(UserSchema, "PaginatedUsers");
+ */
+export declare function paginatedResponse<T extends ZodType>(itemSchema: T, name: string): z.ZodObject<{
+    items: z.ZodArray<T>;
+    total: z.ZodNumber;
+    limit: z.ZodNumber;
+    offset: z.ZodNumber;
+}, z.core.$strip>;
+export interface CursorParamDefaults {
+    /** Default: 50 */
+    limit?: number;
+    /** Default: 200 */
+    maxLimit?: number;
+}
+export interface ParsedCursorParams {
+    limit: number;
+    cursor: string | undefined;
+}
+export interface CursorResult<T> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/**
+ * Zod schema for cursor pagination query params.
+ * Fields are `z.string().optional()`. Parse the values with `parseCursorParams`.
+ *
+ * @example
+ * createRoute({ ..., request: { query: cursorParams() }, ... })
+ */
+export declare function cursorParams(defaults?: CursorParamDefaults): z.ZodObject<{
+    limit: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Parses raw string query values into typed cursor params.
+ * - limit: NaN falls back to default, clamped to [1, maxLimit]
+ * - cursor: empty string normalized to `undefined`; non-empty is pass-through
+ * - When `signing.cursors: true`, verifies the cursor HMAC — invalid cursor returns null
+ *
+ * @example
+ * const { limit, cursor } = parseCursorParams(c.req.query());
+ */
+export declare function parseCursorParams(raw: {
+    limit?: string;
+    cursor?: string;
+}, defaults?: CursorParamDefaults): ParsedCursorParams & {
+    invalidCursor?: true;
+};
+/**
+ * Sign a cursor value if `signing.cursors: true`. Otherwise returns the
+ * cursor unchanged (current behavior).
+ */
+export declare function maybeSignCursor(cursor: string | null): string | null;
+/**
+ * Zod schema factory for cursor-paginated responses.
+ * Wraps `itemSchema` in `{ items, nextCursor, hasMore }` and registers
+ * the result as a named OpenAPI component.
+ *
+ * Throws if `name` was previously registered to a different schema instance.
+ * Calling with the same `name` + `schema` pair is idempotent.
+ *
+ * @example
+ * const PostsPage = cursorResponse(PostSchema, "PostsPage");
+ */
+export declare function cursorResponse<T extends ZodType>(itemSchema: T, name: string): z.ZodObject<{
+    items: z.ZodArray<T>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;

package/dist/lib/pagination.js

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { registerSchema } from "./createRoute";
+import { getSigningConfig, getSigningSecret } from "./appConfig";
+import { signCursor, verifyCursor } from "./signing";
+const _registered = new Map();
+function guardedRegister(name, itemSchema, buildWrapper) {
+    const existing = _registered.get(name);
+    if (existing !== undefined) {
+        if (existing.itemSchema !== itemSchema) {
+            throw new Error(`Pagination schema name "${name}" is already registered to a different schema`);
+        }
+        // Same item schema → idempotent, return the cached wrapper
+        return existing.wrapper;
+    }
+    const wrapper = buildWrapper();
+    _registered.set(name, { itemSchema, wrapper });
+    registerSchema(name, wrapper);
+    return wrapper;
+}
+/**
+ * Zod schema for offset pagination query params.
+ * Fields are `z.string().optional()` — matches the existing query param
+ * convention. Parse the values with `parseOffsetParams`.
+ *
+ * @example
+ * createRoute({ ..., request: { query: offsetParams({ limit: 20 }) }, ... })
+ */
+export function offsetParams(defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const defaultOffset = defaults?.offset ?? 0;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    return z.object({
+        limit: z
+            .string()
+            .optional()
+            .describe(`Number of items to return (1–${maxLimit}, default ${defaultLimit})`),
+        offset: z
+            .string()
+            .optional()
+            .describe(`Number of items to skip (default ${defaultOffset})`),
+    });
+}
+/**
+ * Parses raw string query values into clamped integers.
+ * - NaN (non-numeric strings) falls back to defaults
+ * - limit clamped to [1, maxLimit]
+ * - offset clamped to [0, ∞)
+ *
+ * @example
+ * const { limit, offset } = parseOffsetParams(c.req.query(), { maxLimit: 100 });
+ */
+export function parseOffsetParams(raw, defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    const defaultOffset = defaults?.offset ?? 0;
+    const rawLimit = parseInt(raw.limit ?? "", 10);
+    const rawOffset = parseInt(raw.offset ?? "", 10);
+    const limit = isNaN(rawLimit)
+        ? defaultLimit
+        : Math.min(Math.max(rawLimit, 1), maxLimit);
+    const offset = isNaN(rawOffset) ? defaultOffset : Math.max(rawOffset, 0);
+    return { limit, offset };
+}
+/**
+ * Zod schema factory for paginated offset responses.
+ * Wraps `itemSchema` in `{ items, total, limit, offset }` and registers
+ * the result as a named OpenAPI component.
+ *
+ * Throws if `name` was previously registered to a different schema instance.
+ * Calling with the same `name` + `schema` pair is idempotent.
+ *
+ * @example
+ * const PaginatedUsersResponse = paginatedResponse(UserSchema, "PaginatedUsers");
+ */
+export function paginatedResponse(itemSchema, name) {
+    return guardedRegister(name, itemSchema, () => z.object({
+        items: z.array(itemSchema),
+        total: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+    }));
+}
+/**
+ * Zod schema for cursor pagination query params.
+ * Fields are `z.string().optional()`. Parse the values with `parseCursorParams`.
+ *
+ * @example
+ * createRoute({ ..., request: { query: cursorParams() }, ... })
+ */
+export function cursorParams(defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    return z.object({
+        limit: z
+            .string()
+            .optional()
+            .describe(`Number of items to return (1–${maxLimit}, default ${defaultLimit})`),
+        cursor: z
+            .string()
+            .optional()
+            .describe("Opaque cursor from a previous response's nextCursor field"),
+    });
+}
+/**
+ * Parses raw string query values into typed cursor params.
+ * - limit: NaN falls back to default, clamped to [1, maxLimit]
+ * - cursor: empty string normalized to `undefined`; non-empty is pass-through
+ * - When `signing.cursors: true`, verifies the cursor HMAC — invalid cursor returns null
+ *
+ * @example
+ * const { limit, cursor } = parseCursorParams(c.req.query());
+ */
+export function parseCursorParams(raw, defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    const rawLimit = parseInt(raw.limit ?? "", 10);
+    const limit = isNaN(rawLimit)
+        ? defaultLimit
+        : Math.min(Math.max(rawLimit, 1), maxLimit);
+    if (!raw.cursor)
+        return { limit, cursor: undefined };
+    const cfg = getSigningConfig();
+    if (cfg?.cursors) {
+        const secret = getSigningSecret();
+        if (secret) {
+            const verified = verifyCursor(raw.cursor, secret);
+            if (verified === null)
+                return { limit, cursor: undefined, invalidCursor: true };
+            return { limit, cursor: verified };
+        }
+    }
+    return { limit, cursor: raw.cursor };
+}
+/**
+ * Sign a cursor value if `signing.cursors: true`. Otherwise returns the
+ * cursor unchanged (current behavior).
+ */
+export function maybeSignCursor(cursor) {
+    if (!cursor)
+        return cursor;
+    const cfg = getSigningConfig();
+    if (cfg?.cursors) {
+        const secret = getSigningSecret();
+        if (secret)
+            return signCursor(cursor, secret);
+    }
+    return cursor;
+}
+/**
+ * Zod schema factory for cursor-paginated responses.
+ * Wraps `itemSchema` in `{ items, nextCursor, hasMore }` and registers
+ * the result as a named OpenAPI component.
+ *
+ * Throws if `name` was previously registered to a different schema instance.
+ * Calling with the same `name` + `schema` pair is idempotent.
+ *
+ * @example
+ * const PostsPage = cursorResponse(PostSchema, "PostsPage");
+ */
+export function cursorResponse(itemSchema, name) {
+    return guardedRegister(name, itemSchema, () => z.object({
+        items: z.array(itemSchema),
+        nextCursor: z.string().nullable(),
+        hasMore: z.boolean(),
+    }));
+}

package/dist/lib/resetPassword.js

@@ -44,7 +44,9 @@ export const setPasswordResetStore = (store) => { _store = store; };
 /** Create a reset token. Returns the raw token (to embed in the email link).
  *  Only the SHA-256 hash is persisted in the store. */
 export const createResetToken = async (userId, email) => {
-    const token = crypto.randomUUID();
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    const token = Buffer.from(bytes).toString("base64url");
     const hash = hashToken(token);
     const ttl = getResetTokenExpiry();
     if (_store === "memory") {

package/dist/lib/saml.d.ts

@@ -0,0 +1,25 @@
+import type { IdentityProfile } from "./authAdapter";
+export interface SamlProfile {
+    nameId: string;
+    nameIdFormat?: string;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    groups?: string[];
+    attributes: Record<string, string | string[]>;
+}
+export interface SamlAttributeMapping {
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    groups?: string;
+}
+export declare function initSaml(config: import("./appConfig").SamlConfig): Promise<void>;
+export declare function createAuthnRequest(): {
+    redirectUrl: string;
+    id: string;
+};
+export declare function validateSamlResponse(body: string, config: import("./appConfig").SamlConfig): Promise<SamlProfile>;
+export declare function samlProfileToIdentityProfile(profile: SamlProfile): IdentityProfile;
+export declare function getSamlSpMetadata(): string;

package/dist/lib/saml.js

@@ -0,0 +1,64 @@
+let _sp = null;
+let _idp = null;
+export async function initSaml(config) {
+    const samlify = await import("samlify");
+    _sp = samlify.ServiceProvider({
+        entityID: config.entityId,
+        assertionConsumerService: [{
+                Binding: samlify.Constants.BindingNamespace.Post,
+                Location: config.acsUrl,
+            }],
+        signingCert: config.signingCert,
+        privateKey: config.signingKey,
+        allowCreate: true,
+    });
+    // Load IdP metadata
+    if (config.idpMetadata.startsWith("http")) {
+        // URL — fetch it
+        const res = await fetch(config.idpMetadata);
+        const xml = await res.text();
+        _idp = samlify.IdentityProvider({ metadata: xml });
+    }
+    else {
+        // XML string
+        _idp = samlify.IdentityProvider({ metadata: config.idpMetadata });
+    }
+}
+export function createAuthnRequest() {
+    if (!_sp || !_idp)
+        throw new Error("SAML not initialized");
+    const { context, entityEndpoint } = _sp.createLoginRequest(_idp, "redirect");
+    return { redirectUrl: entityEndpoint + "?" + context, id: context };
+}
+export async function validateSamlResponse(body, config) {
+    if (!_sp || !_idp)
+        throw new Error("SAML not initialized");
+    const { extract } = await _sp.parseLoginResponse(_idp, "post", { body: { SAMLResponse: body } });
+    const mapping = config.attributeMapping ?? {};
+    const attrs = extract.attributes ?? {};
+    const emailKey = mapping.email ?? "email";
+    const firstNameKey = mapping.firstName ?? "firstName";
+    const lastNameKey = mapping.lastName ?? "lastName";
+    const groupsKey = mapping.groups ?? "groups";
+    const nameId = extract.nameID;
+    const email = attrs[emailKey] ?? nameId;
+    const firstName = attrs[firstNameKey];
+    const lastName = attrs[lastNameKey];
+    const displayName = firstName && lastName ? `${firstName} ${lastName}` : undefined;
+    const rawGroups = attrs[groupsKey];
+    const groups = rawGroups ? (Array.isArray(rawGroups) ? rawGroups : [rawGroups]) : undefined;
+    return { nameId, email, firstName, lastName, displayName, groups, attributes: attrs };
+}
+export function samlProfileToIdentityProfile(profile) {
+    return {
+        email: profile.email,
+        displayName: profile.displayName,
+        firstName: profile.firstName,
+        lastName: profile.lastName,
+    };
+}
+export function getSamlSpMetadata() {
+    if (!_sp)
+        throw new Error("SAML not initialized");
+    return _sp.getMetadata();
+}

package/dist/lib/scim.d.ts

@@ -0,0 +1,44 @@
+import type { UserRecord } from "./authAdapter";
+export interface ScimUser {
+    schemas: ["urn:ietf:params:scim:schemas:core:2.0:User"];
+    id: string;
+    externalId?: string;
+    userName: string;
+    displayName?: string;
+    name?: {
+        givenName?: string;
+        familyName?: string;
+        formatted?: string;
+    };
+    emails?: Array<{
+        value: string;
+        primary: boolean;
+    }>;
+    active: boolean;
+    meta: {
+        resourceType: "User";
+        created?: string;
+        lastModified?: string;
+    };
+}
+export interface ScimListResponse {
+    schemas: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"];
+    totalResults: number;
+    startIndex: number;
+    itemsPerPage: number;
+    Resources: ScimUser[];
+}
+export interface ScimError {
+    schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"];
+    status: string;
+    detail: string;
+}
+export declare function userRecordToScim(user: UserRecord, config?: {
+    userName?: "email" | "username";
+}): ScimUser;
+/**
+ * Parse a simple SCIM filter string into a UserQuery object.
+ * Supports: userName eq "val", email eq "val", externalId eq "val", active eq true/false
+ */
+export declare function parseScimFilter(filter?: string): import("./authAdapter").UserQuery;
+export declare function scimError(status: number, detail: string): Response;

package/dist/lib/scim.js

@@ -0,0 +1,54 @@
+export function userRecordToScim(user, config) {
+    const userName = user.email ?? user.id;
+    return {
+        schemas: ["urn:ietf:params:scim:schemas:core:2.0:User"],
+        id: user.id,
+        externalId: user.externalId,
+        userName,
+        displayName: user.displayName,
+        name: (user.firstName || user.lastName) ? {
+            givenName: user.firstName,
+            familyName: user.lastName,
+            formatted: [user.firstName, user.lastName].filter(Boolean).join(" ") || undefined,
+        } : undefined,
+        emails: user.email ? [{ value: user.email, primary: true }] : undefined,
+        active: !user.suspended,
+        meta: { resourceType: "User" },
+    };
+}
+/**
+ * Parse a simple SCIM filter string into a UserQuery object.
+ * Supports: userName eq "val", email eq "val", externalId eq "val", active eq true/false
+ */
+export function parseScimFilter(filter) {
+    if (!filter)
+        return {};
+    const query = {};
+    // Simple single-clause filter: `attr op "value"`
+    const match = filter.trim().match(/^(\w+)\s+eq\s+"?([^"]*)"?$/i);
+    if (!match)
+        return {};
+    const [, attr, value] = match;
+    const attrLower = attr.toLowerCase();
+    if (attrLower === "username" || attrLower === "email") {
+        query.email = value;
+    }
+    else if (attrLower === "externalid") {
+        query.externalId = value;
+    }
+    else if (attrLower === "active") {
+        query.suspended = value.toLowerCase() !== "true"; // active=true means suspended=false
+    }
+    return query;
+}
+export function scimError(status, detail) {
+    const body = {
+        schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+        status: String(status),
+        detail,
+    };
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/scim+json" },
+    });
+}

package/dist/lib/securityEvents.d.ts

@@ -0,0 +1,28 @@
+export type SecurityEventType = "auth.login.success" | "auth.login.failure" | "auth.login.blocked" | "auth.register.success" | "auth.register.failure" | "auth.logout" | "auth.password.reset" | "auth.password.change" | "auth.mfa.setup" | "auth.mfa.verify.success" | "auth.mfa.verify.failure" | "auth.step_up.success" | "auth.step_up.failure" | "auth.session.created" | "auth.session.revoked" | "auth.account.suspended" | "auth.account.deleted" | "auth.oauth.link" | "auth.oauth.unlink" | "security.rate_limit.exceeded" | "security.credential_stuffing.detected" | "security.captcha.failed" | "security.csrf.failed" | "security.breached_password.detected" | "admin.role.changed" | "admin.user.modified";
+export interface SecurityEvent {
+    eventType: SecurityEventType;
+    severity: "info" | "warn" | "critical";
+    timestamp: string;
+    requestId?: string;
+    userId?: string;
+    sessionId?: string;
+    tenantId?: string;
+    ip?: string;
+    userAgent?: string;
+    meta?: Record<string, unknown>;
+}
+export interface SecurityEventConfig {
+    /** Called for each security event. Non-blocking — errors are swallowed. */
+    onEvent: (event: SecurityEvent) => void | Promise<void>;
+    /** Only emit events of these types. If omitted, all events are emitted. */
+    include?: SecurityEventType[];
+    /** Skip events of these types. Applied after include. */
+    exclude?: SecurityEventType[];
+}
+export declare function setSecurityEventConfig(config: SecurityEventConfig | null): void;
+export declare function getSecurityEventConfig(): SecurityEventConfig | null;
+/**
+ * Emit a security event. Non-blocking — the call returns immediately.
+ * If onEvent throws, the error is silently swallowed (never propagates to the caller).
+ */
+export declare function emitSecurityEvent(event: SecurityEvent): void;

package/dist/lib/securityEvents.js

@@ -0,0 +1,26 @@
+let _config = null;
+export function setSecurityEventConfig(config) {
+    _config = config;
+}
+export function getSecurityEventConfig() {
+    return _config;
+}
+/**
+ * Emit a security event. Non-blocking — the call returns immediately.
+ * If onEvent throws, the error is silently swallowed (never propagates to the caller).
+ */
+export function emitSecurityEvent(event) {
+    if (!_config)
+        return;
+    const { onEvent, include, exclude } = _config;
+    if (include && include.length > 0 && !include.includes(event.eventType))
+        return;
+    if (exclude && exclude.includes(event.eventType))
+        return;
+    // Fire and forget — never block the request
+    Promise.resolve()
+        .then(() => onEvent({ ...event, timestamp: event.timestamp ?? new Date().toISOString() }))
+        .catch(() => {
+        // Swallow errors — security event emission must never crash the app
+    });
+}

package/dist/lib/session.d.ts

@@ -32,4 +32,18 @@ export declare const setRefreshToken: (sessionId: string, refreshToken: string)
 export declare const getSessionByRefreshToken: (refreshToken: string) => Promise<RefreshResult | null>;
 /** Rotate the refresh token: move current to prev with grace window, set new token + access token. */
 export declare const rotateRefreshToken: (sessionId: string, newRefreshToken: string, newAccessToken: string) => Promise<void>;
+/** Read the stored fingerprint for a session. Returns null if not yet set. */
+export declare const getSessionFingerprint: (sessionId: string) => Promise<string | null>;
+/** Store a fingerprint on an existing session. No-op if the session does not exist. */
+export declare const setSessionFingerprint: (sessionId: string, fingerprint: string) => Promise<void>;
+/**
+ * Store the timestamp when MFA was last verified in the session metadata.
+ * Used by requireStepUp middleware.
+ */
+export declare const setMfaVerifiedAt: (sessionId: string) => Promise<void>;
+/**
+ * Get the Unix timestamp (seconds) when MFA was last verified for this session.
+ * Returns null if MFA has never been verified or session not found.
+ */
+export declare const getMfaVerifiedAt: (sessionId: string) => Promise<number | null>;
 export {};