@lastshotlabs/bunshot 0.0.25 → 0.0.28

package/dist/packages/bunshot-core/src/auth-adapter.d.ts

@@ -0,0 +1,227 @@
+export interface IdentityProfile {
+    email?: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    externalId?: string;
+}
+export interface WebAuthnCredential {
+    /** Base64url-encoded credential ID. */
+    credentialId: string;
+    /** Base64url-encoded public key. */
+    publicKey: string;
+    /** Counter for signature verification (replay protection). */
+    signCount: number;
+    /** Transport hints from the authenticator (usb, ble, nfc, internal). */
+    transports?: string[];
+    /** User-assigned name for the key (e.g. "YubiKey 5"). */
+    name?: string;
+    /** When the credential was registered (epoch ms). */
+    createdAt: number;
+}
+export interface M2MClientRecord {
+    id: string;
+    clientId: string;
+    name: string;
+    scopes: string[];
+    active: boolean;
+}
+export interface UserQuery {
+    email?: string;
+    externalId?: string;
+    suspended?: boolean;
+    startIndex?: number;
+    count?: number;
+}
+export interface UserRecord {
+    id: string;
+    email?: string;
+    displayName?: string;
+    firstName?: string;
+    lastName?: string;
+    externalId?: string;
+    suspended: boolean;
+    suspendedAt?: Date;
+    suspendedReason?: string;
+    emailVerified?: boolean;
+    providerIds?: string[];
+    userMetadata?: Record<string, unknown>;
+    appMetadata?: Record<string, unknown>;
+}
+export interface GroupRecord {
+    id: string;
+    /** Machine-readable slug: /^[a-z0-9_-]+$/, unique within scope (app-wide or per-tenant). */
+    name: string;
+    displayName?: string;
+    description?: string;
+    /** Baseline roles granted to every member of this group. */
+    roles: string[];
+    /** null = app-wide group, string = tenant-scoped group. Immutable after creation. */
+    tenantId: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface GroupMembershipRecord {
+    userId: string;
+    groupId: string;
+    /** Per-member extra roles on top of the group's baseline roles. */
+    roles: string[];
+    /**
+     * Denormalized from the group at insert time for efficient tenant-scoped queries.
+     * Immutable: the group's tenantId cannot change after creation, so this is always consistent.
+     */
+    tenantId: string | null;
+    createdAt: number;
+}
+export interface PaginationOpts {
+    /** Default: 50, max: 200 */
+    limit?: number;
+    /** Opaque pagination cursor from a previous response */
+    cursor?: string;
+}
+export interface PaginatedResult<T> {
+    items: T[];
+    nextCursor?: string;
+}
+export interface CoreAuthAdapter {
+    /** Required. Look up a user by email address. */
+    findByEmail(email: string): Promise<{
+        id: string;
+        passwordHash: string;
+    } | null>;
+    /** Required. Create a new user with email and password hash. */
+    create(email: string, passwordHash: string): Promise<{
+        id: string;
+    }>;
+    /** Required. Verify a user's password by userId without exposing the hash. */
+    verifyPassword(userId: string, password: string): Promise<boolean>;
+    /** Required. Return the primary login identifier for a user. */
+    getIdentifier(userId: string): Promise<string>;
+    getUser?(userId: string): Promise<{
+        email?: string;
+        providerIds?: string[];
+        emailVerified?: boolean;
+        displayName?: string;
+        firstName?: string;
+        lastName?: string;
+        externalId?: string;
+        suspended?: boolean;
+        suspendedReason?: string;
+        userMetadata?: Record<string, unknown>;
+        appMetadata?: Record<string, unknown>;
+    } | null>;
+    setPassword?(userId: string, passwordHash: string): Promise<void>;
+    deleteUser?(userId: string): Promise<void>;
+    setEmailVerified?(userId: string, verified: boolean): Promise<void>;
+    getEmailVerified?(userId: string): Promise<boolean>;
+    hasPassword?(userId: string): Promise<boolean>;
+    findByIdentifier?(value: string): Promise<{
+        id: string;
+        passwordHash: string;
+    } | null>;
+    updateProfile?(userId: string, fields: {
+        displayName?: string;
+        firstName?: string;
+        lastName?: string;
+        externalId?: string;
+    }): Promise<void>;
+    getUserMetadata?(userId: string): Promise<{
+        userMetadata?: Record<string, unknown>;
+        appMetadata?: Record<string, unknown>;
+    }>;
+    setUserMetadata?(userId: string, data: Record<string, unknown>): Promise<void>;
+    setAppMetadata?(userId: string, data: Record<string, unknown>): Promise<void>;
+    /** Required when MFA is configured — atomically find and remove a hashed recovery code. */
+    consumeRecoveryCode(userId: string, hashedCode: string): Promise<boolean>;
+}
+export interface OAuthAdapter {
+    /** Required when using OAuth providers. Find or create a user by provider + provider user ID. */
+    findOrCreateByProvider(provider: string, providerId: string, profile: IdentityProfile): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    /** Required when using OAuth link routes. */
+    linkProvider(userId: string, provider: string, providerId: string): Promise<void>;
+    /** Required when using OAuth unlink routes. */
+    unlinkProvider(userId: string, provider: string): Promise<void>;
+}
+export interface MfaAdapter {
+    setMfaSecret(userId: string, secret: string | null): Promise<void>;
+    getMfaSecret(userId: string): Promise<string | null>;
+    isMfaEnabled(userId: string): Promise<boolean>;
+    setMfaEnabled(userId: string, enabled: boolean): Promise<void>;
+    setRecoveryCodes(userId: string, codes: string[]): Promise<void>;
+    getRecoveryCodes(userId: string): Promise<string[]>;
+    removeRecoveryCode(userId: string, code: string): Promise<void>;
+    getMfaMethods?(userId: string): Promise<string[]>;
+    setMfaMethods?(userId: string, methods: string[]): Promise<void>;
+}
+export interface WebAuthnAdapter {
+    getWebAuthnCredentials(userId: string): Promise<WebAuthnCredential[]>;
+    addWebAuthnCredential(userId: string, credential: WebAuthnCredential): Promise<void>;
+    removeWebAuthnCredential(userId: string, credentialId: string): Promise<void>;
+    updateWebAuthnCredentialSignCount(userId: string, credentialId: string, signCount: number): Promise<void>;
+    findUserByWebAuthnCredentialId(credentialId: string): Promise<string | null>;
+}
+export interface RolesAdapter {
+    getRoles(userId: string): Promise<string[]>;
+    setRoles(userId: string, roles: string[]): Promise<void>;
+    addRole(userId: string, role: string): Promise<void>;
+    removeRole(userId: string, role: string): Promise<void>;
+    getTenantRoles?(userId: string, tenantId: string): Promise<string[]>;
+    setTenantRoles?(userId: string, tenantId: string, roles: string[]): Promise<void>;
+    addTenantRole?(userId: string, tenantId: string, role: string): Promise<void>;
+    removeTenantRole?(userId: string, tenantId: string, role: string): Promise<void>;
+}
+export interface GroupsAdapter {
+    createGroup(group: Omit<GroupRecord, 'id' | 'createdAt' | 'updatedAt'>): Promise<{
+        id: string;
+    }>;
+    deleteGroup(groupId: string): Promise<void>;
+    getGroup(groupId: string): Promise<GroupRecord | null>;
+    listGroups(tenantId: string | null, opts?: PaginationOpts): Promise<PaginatedResult<GroupRecord>>;
+    updateGroup(groupId: string, updates: Partial<Pick<GroupRecord, 'roles' | 'name' | 'displayName' | 'description'>>): Promise<void>;
+    addGroupMember(groupId: string, userId: string, roles?: string[]): Promise<void>;
+    updateGroupMembership(groupId: string, userId: string, roles: string[]): Promise<void>;
+    removeGroupMember(groupId: string, userId: string): Promise<void>;
+    getGroupMembers(groupId: string, opts?: PaginationOpts): Promise<PaginatedResult<{
+        userId: string;
+        roles: string[];
+    }>>;
+    getUserGroups(userId: string, tenantId: string | null): Promise<Array<{
+        group: GroupRecord;
+        membershipRoles: string[];
+    }>>;
+    getEffectiveRoles(userId: string, tenantId: string | null): Promise<string[]>;
+}
+export interface SuspensionAdapter {
+    setSuspended(userId: string, suspended: boolean, reason?: string): Promise<void>;
+    getSuspended(userId: string): Promise<{
+        suspended: boolean;
+        suspendedReason?: string;
+    } | null>;
+}
+export interface EnterpriseAdapter {
+    getM2MClient?(clientId: string): Promise<(M2MClientRecord & {
+        clientSecretHash: string;
+    }) | null>;
+    createM2MClient?(client: {
+        clientId: string;
+        clientSecretHash: string;
+        name: string;
+        scopes: string[];
+    }): Promise<{
+        id: string;
+    }>;
+    deleteM2MClient?(clientId: string): Promise<void>;
+    listM2MClients?(): Promise<M2MClientRecord[]>;
+    listUsers?(query: UserQuery): Promise<{
+        users: UserRecord[];
+        totalResults: number;
+    }>;
+    getPasswordHistory?(userId: string): Promise<string[]>;
+    addPasswordToHistory?(userId: string, hash: string, maxCount: number): Promise<void>;
+}
+export type AuthAdapter = CoreAuthAdapter & Partial<OAuthAdapter> & Partial<MfaAdapter> & Partial<WebAuthnAdapter> & Partial<RolesAdapter> & Partial<GroupsAdapter> & Partial<SuspensionAdapter> & Partial<EnterpriseAdapter>;

package/dist/packages/bunshot-core/src/auth-adapter.js

@@ -0,0 +1,4 @@
+// Core AuthAdapter type contracts.
+// These live in bunshot-core so adapter packages (e.g. bunshot-postgres) can depend
+// on core alone instead of pulling in the full auth plugin.
+export {};

package/dist/packages/bunshot-core/src/authVariables.d.ts

@@ -0,0 +1,14 @@
+export interface AuthVariables {
+    /** Authenticated user ID from the JWT sid claim. Null when unauthenticated. */
+    authUserId: string | null;
+    /** Session ID from the JWT sid claim. Null when unauthenticated. */
+    sessionId: string | null;
+    /** Effective roles for the authenticated user. Null when unauthenticated. */
+    roles: string[] | null;
+    /** Set by identify when a scope-bearing M2M token (no sid) is verified. */
+    authClientId: string | null;
+    /** Set by bearerAuth when a BearerAuthClient match is found (clientId from the matched entry). */
+    bearerClientId: string | null;
+    /** Raw verified JWT payload stashed by identify for downstream middleware. Null when unauthenticated. */
+    tokenPayload: unknown | null;
+}

package/dist/packages/bunshot-core/src/authVariables.js

@@ -0,0 +1,4 @@
+// Auth-specific Hono context variables.
+// Set by identity middleware (identify, bearerAuth) on each request.
+// Merged into AppEnv in context.ts.
+export {};

package/dist/packages/bunshot-core/src/cache.d.ts

@@ -0,0 +1,12 @@
+import { type ContextCarrier } from './context/contextAccess';
+import type { CacheAdapter, CacheStoreName } from './coreContracts';
+export type { CacheAdapter, CacheStoreName };
+/**
+ * Cache adapter for framework response caching.
+ *
+ * Implementations provide get/set/del/delPattern for a single backing store.
+ * The framework's cacheResponse middleware delegates to whichever adapter
+ * is resolved for the configured store type on the app instance.
+ */
+export declare function getCacheAdapter(input: ContextCarrier, store: CacheStoreName): CacheAdapter;
+export declare function getCacheAdapterOrNull(input: ContextCarrier, store: CacheStoreName): CacheAdapter | null;

package/dist/packages/bunshot-core/src/cache.js

@@ -0,0 +1,21 @@
+import { resolveContext } from './context/contextAccess';
+// ---------------------------------------------------------------------------
+// CacheAdapter -- unified cache interface for framework response caching.
+// ---------------------------------------------------------------------------
+/**
+ * Cache adapter for framework response caching.
+ *
+ * Implementations provide get/set/del/delPattern for a single backing store.
+ * The framework's cacheResponse middleware delegates to whichever adapter
+ * is resolved for the configured store type on the app instance.
+ */
+export function getCacheAdapter(input, store) {
+    const adapter = resolveContext(input).cacheAdapters.get(store);
+    if (!adapter) {
+        throw new Error(`No CacheAdapter registered for store "${store}" on this app instance.`);
+    }
+    return adapter;
+}
+export function getCacheAdapterOrNull(input, store) {
+    return resolveContext(input).cacheAdapters.get(store) ?? null;
+}

package/dist/packages/bunshot-core/src/captcha.d.ts

@@ -0,0 +1,16 @@
+export type CaptchaProvider = 'recaptcha' | 'hcaptcha' | 'turnstile';
+export interface CaptchaConfig {
+    provider: CaptchaProvider;
+    secretKey: string;
+    /** Minimum score for reCAPTCHA v3. Default: 0.5. Ignored for v2/hcaptcha/turnstile. */
+    minScore?: number;
+    /** Body field name containing the CAPTCHA token. Default: "captcha-token". */
+    tokenField?: string;
+    /** When true, only require CAPTCHA after rate limit threshold is hit. Default: false. */
+    adaptive?: boolean;
+    /** Rate limit window for adaptive mode. */
+    adaptiveThreshold?: {
+        windowMs: number;
+        max: number;
+    };
+}

package/dist/packages/bunshot-core/src/captcha.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/clearRegistry.d.ts

@@ -0,0 +1,6 @@
+/** Register a cleanup function to be called by runAllClearCallbacks(). */
+export declare function registerClearCallback(fn: () => void): void;
+/** Run all registered cleanup callbacks. */
+export declare function runAllClearCallbacks(): void;
+/** Reset the registry itself (for test isolation of the registry). */
+export declare function resetClearRegistry(): void;

package/dist/packages/bunshot-core/src/clearRegistry.js

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// Clear callback registry — unified teardown for test isolation
+// ---------------------------------------------------------------------------
+const _clearCallbacks = [];
+/** Register a cleanup function to be called by runAllClearCallbacks(). */
+export function registerClearCallback(fn) {
+    _clearCallbacks.push(fn);
+}
+/** Run all registered cleanup callbacks. */
+export function runAllClearCallbacks() {
+    for (const fn of _clearCallbacks)
+        fn();
+}
+/** Reset the registry itself (for test isolation of the registry). */
+export function resetClearRegistry() {
+    _clearCallbacks.length = 0;
+}

package/dist/packages/bunshot-core/src/clientIp.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from 'hono';
+export declare const setStandaloneTrustProxy: (req: Request, value: false | number) => void;
+export declare const getClientIp: (c: Context<any>) => string;

package/dist/packages/bunshot-core/src/clientIp.js

@@ -0,0 +1,45 @@
+const TRUST_PROXY_SYMBOL = Symbol.for('bunshot.trustProxy');
+export const setStandaloneTrustProxy = (req, value) => {
+    Object.defineProperty(req, TRUST_PROXY_SYMBOL, {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value,
+    });
+};
+const normalizeIp = (ip) => (ip.startsWith('::ffff:') ? ip.slice(7) : ip);
+export const getClientIp = (c) => {
+    const bunshotCtx = typeof c.get === 'function'
+        ? c.get('bunshotCtx')
+        : undefined;
+    const trustProxy = bunshotCtx?.trustProxy ??
+        c.req.raw[TRUST_PROXY_SYMBOL] ??
+        false;
+    let socketIp;
+    try {
+        const server = c.env;
+        if (server?.requestIP) {
+            const info = server.requestIP(c.req.raw);
+            if (info)
+                socketIp = info.address;
+        }
+    }
+    catch { }
+    if (trustProxy === false) {
+        return normalizeIp(socketIp ?? 'unknown');
+    }
+    const xff = c.req.header('x-forwarded-for');
+    if (xff) {
+        const ips = xff
+            .split(',')
+            .map(s => s.trim())
+            .filter(Boolean);
+        const idx = ips.length - trustProxy - 1;
+        if (idx >= 0 && ips[idx]) {
+            return normalizeIp(ips[idx]);
+        }
+        return normalizeIp(socketIp ?? 'unknown');
+    }
+    const realIp = c.req.header('x-real-ip');
+    return normalizeIp(realIp ?? socketIp ?? 'unknown');
+};

package/dist/packages/bunshot-core/src/configLock.d.ts

@@ -0,0 +1,4 @@
+export declare function lockCoreConfig(): void;
+export declare function isCoreConfigLocked(): boolean;
+export declare function unlockCoreConfig(): void;
+export declare function assertCoreConfigNotLocked(): void;

package/dist/packages/bunshot-core/src/configLock.js

@@ -0,0 +1,7 @@
+// Core config lock removed. Core runtime state is now instance-owned.
+export function lockCoreConfig() { }
+export function isCoreConfigLocked() {
+    return false;
+}
+export function unlockCoreConfig() { }
+export function assertCoreConfigNotLocked() { }

package/dist/packages/bunshot-core/src/configValidation.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/**
+ * Build the standard `disableRoutes` Zod field for a plugin config schema.
+ * Pass the values array from a route-name constant object.
+ *
+ * @example
+ * disableRoutes: disableRoutesSchema(Object.values(COMMUNITY_ROUTES)),
+ */
+export declare function disableRoutesSchema<T extends string>(values: readonly T[]): z.ZodOptional<z.ZodArray<z.ZodEnum<{ [k_1 in T]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>>>;
+/**
+ * Warn about unknown keys in a plugin config object.
+ * Compares Object.keys(raw) against the Zod schema's known shape keys.
+ * Logs a warning for each unknown key — does not throw.
+ */
+export declare function warnUnknownPluginKeys(pluginName: string, raw: Record<string, unknown>, schema: z.ZodObject<any>): void;
+/**
+ * Validate a plugin config using its Zod schema.
+ * Throws on missing required keys or type mismatches with a formatted error.
+ * Warns on unknown keys (does not throw).
+ * Returns the parsed config.
+ */
+export declare function validatePluginConfig<T>(pluginName: string, rawConfig: Record<string, unknown>, schema: z.ZodObject<any>): T;

package/dist/packages/bunshot-core/src/configValidation.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+/**
+ * Build the standard `disableRoutes` Zod field for a plugin config schema.
+ * Pass the values array from a route-name constant object.
+ *
+ * @example
+ * disableRoutes: disableRoutesSchema(Object.values(COMMUNITY_ROUTES)),
+ */
+export function disableRoutesSchema(values) {
+    return z.array(z.enum(values)).optional();
+}
+/**
+ * Warn about unknown keys in a plugin config object.
+ * Compares Object.keys(raw) against the Zod schema's known shape keys.
+ * Logs a warning for each unknown key — does not throw.
+ */
+export function warnUnknownPluginKeys(pluginName, raw, schema) {
+    const known = new Set(Object.keys(schema.shape));
+    for (const key of Object.keys(raw)) {
+        if (!known.has(key)) {
+            console.warn(`[${pluginName}] Unknown config key "${key}" — will be ignored. Check for typos.`);
+        }
+    }
+}
+/**
+ * Validate a plugin config using its Zod schema.
+ * Throws on missing required keys or type mismatches with a formatted error.
+ * Warns on unknown keys (does not throw).
+ * Returns the parsed config.
+ */
+export function validatePluginConfig(pluginName, rawConfig, schema) {
+    const result = schema.safeParse(rawConfig);
+    if (!result.success) {
+        const issues = result.error.issues.map(i => `  - ${i.path.join('.')}: ${i.message}`).join('\n');
+        throw new Error(`[${pluginName}] Invalid plugin config:\n${issues}`);
+    }
+    warnUnknownPluginKeys(pluginName, rawConfig, schema);
+    return result.data;
+}

package/dist/packages/bunshot-core/src/constants.js

@@ -0,0 +1,10 @@
+export const COOKIE_TOKEN = 'token';
+export const HEADER_USER_TOKEN = 'x-user-token';
+export const COOKIE_REFRESH_TOKEN = 'refresh_token';
+export const HEADER_REFRESH_TOKEN = 'x-refresh-token';
+export const COOKIE_CSRF_TOKEN = 'csrf_token';
+export const HEADER_CSRF_TOKEN = 'x-csrf-token';
+export const HEADER_REQUEST_ID = 'x-request-id';
+export const HEADER_IDEMPOTENCY_KEY = 'idempotency-key';
+export const HEADER_SIGNATURE = 'x-signature';
+export const HEADER_TIMESTAMP = 'x-timestamp';