@holeauth/core 0.0.1-alpha.0

package/dist/index-CNtnPdzk.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Adapter interfaces. ORM/database-specific adapters live in separate packages
+ * (e.g. @holeauth/adapter-prisma, @holeauth/adapter-drizzle).
+ *
+ * Plugin-specific data (2FA credentials, passkeys, RBAC assignments, …)
+ * is owned by the plugin's own adapter interface — never carried on the
+ * User row.
+ */
+interface AdapterUser {
+    id: string;
+    email: string;
+    emailVerified?: Date | null;
+    name?: string | null;
+    image?: string | null;
+    passwordHash?: string | null;
+}
+interface AdapterSession {
+    id: string;
+    userId: string;
+    /** Refresh-token family (all rotations in a login chain share this). */
+    familyId: string;
+    /** SHA-256(refreshToken) — never store the raw token. */
+    refreshTokenHash: string;
+    expiresAt: Date;
+    createdAt?: Date;
+    revokedAt?: Date | null;
+    userAgent?: string | null;
+    ip?: string | null;
+}
+interface AdapterAccount {
+    id: string;
+    userId: string;
+    provider: string;
+    providerAccountId: string;
+    email?: string | null;
+    accessToken?: string | null;
+    refreshToken?: string | null;
+    expiresAt?: Date | null;
+    tokenType?: string | null;
+    scope?: string | null;
+    idToken?: string | null;
+}
+interface AdapterVerificationToken {
+    identifier: string;
+    token: string;
+    expiresAt: Date;
+}
+interface AdapterAuditEvent {
+    id?: string;
+    type: string;
+    userId?: string | null;
+    sessionId?: string | null;
+    at?: Date;
+    ip?: string | null;
+    userAgent?: string | null;
+    data?: Record<string, unknown> | null;
+}
+interface UserAdapter {
+    getUserById(id: string): Promise<AdapterUser | null>;
+    getUserByEmail(email: string): Promise<AdapterUser | null>;
+    createUser(data: Omit<AdapterUser, 'id'>): Promise<AdapterUser>;
+    updateUser(id: string, patch: Partial<AdapterUser>): Promise<AdapterUser>;
+    deleteUser(id: string): Promise<void>;
+}
+interface SessionAdapter {
+    /** Persist a session using the provided id (so callers can bind tokens before write). */
+    createSession(data: AdapterSession): Promise<AdapterSession>;
+    getSession(id: string): Promise<AdapterSession | null>;
+    getByRefreshHash(hash: string): Promise<AdapterSession | null>;
+    findByFamily(familyId: string): Promise<AdapterSession[]>;
+    deleteSession(id: string): Promise<void>;
+    /** Replace hash+exp atomically; returns the updated session. */
+    rotateRefresh(id: string, newHash: string, expiresAt: Date): Promise<AdapterSession>;
+    /** Revoke all sessions in a family (reuse-detection response). */
+    revokeFamily(familyId: string): Promise<void>;
+    /** Revoke all sessions for a user (global signout). */
+    revokeUser?(userId: string): Promise<void>;
+}
+interface AccountAdapter {
+    linkAccount(data: Omit<AdapterAccount, 'id'>): Promise<AdapterAccount>;
+    getAccountByProvider(provider: string, providerAccountId: string): Promise<AdapterAccount | null>;
+    getByProviderEmail?(provider: string, email: string): Promise<AdapterAccount | null>;
+    listByUser(userId: string): Promise<AdapterAccount[]>;
+    unlinkAccount(id: string): Promise<void>;
+}
+interface VerificationTokenAdapter {
+    create(data: AdapterVerificationToken): Promise<AdapterVerificationToken>;
+    consume(identifier: string, token: string): Promise<AdapterVerificationToken | null>;
+    /** Optional: purge expired rows (maintenance). */
+    purgeExpired?(): Promise<number>;
+    /** Optional: list all rows whose identifier starts with the given prefix. */
+    listByIdentifierPrefix?(prefix: string): Promise<AdapterVerificationToken[]>;
+    /** Optional: delete all rows with the exact identifier. Returns number of rows removed. */
+    deleteByIdentifier?(identifier: string): Promise<number>;
+}
+interface AuditLogAdapter {
+    /** Persist an event. MUST be awaited by flows. */
+    record(event: AdapterAuditEvent): Promise<void>;
+    list?(filter: {
+        userId?: string;
+        type?: string;
+        limit?: number;
+    }): Promise<AdapterAuditEvent[]>;
+}
+/**
+ * Optional transaction primitive. When provided, multi-step writes
+ * (deleteUser, signout with family revoke, password-change with session
+ * revoke, sso.callback create+link) are wrapped in a transaction.
+ *
+ * Implementations SHOULD propagate the tx through all adapter method
+ * calls invoked inside `fn` (e.g. by returning a fresh adapter bundle
+ * bound to the tx, or by using async-local-storage).
+ *
+ * If no transaction adapter is supplied, core falls back to sequential
+ * execution without atomicity.
+ */
+interface TransactionAdapter {
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+type index_AccountAdapter = AccountAdapter;
+type index_AdapterAccount = AdapterAccount;
+type index_AdapterAuditEvent = AdapterAuditEvent;
+type index_AdapterSession = AdapterSession;
+type index_AdapterUser = AdapterUser;
+type index_AdapterVerificationToken = AdapterVerificationToken;
+type index_AuditLogAdapter = AuditLogAdapter;
+type index_SessionAdapter = SessionAdapter;
+type index_TransactionAdapter = TransactionAdapter;
+type index_UserAdapter = UserAdapter;
+type index_VerificationTokenAdapter = VerificationTokenAdapter;
+declare namespace index {
+  export type { index_AccountAdapter as AccountAdapter, index_AdapterAccount as AdapterAccount, index_AdapterAuditEvent as AdapterAuditEvent, index_AdapterSession as AdapterSession, index_AdapterUser as AdapterUser, index_AdapterVerificationToken as AdapterVerificationToken, index_AuditLogAdapter as AuditLogAdapter, index_SessionAdapter as SessionAdapter, index_TransactionAdapter as TransactionAdapter, index_UserAdapter as UserAdapter, index_VerificationTokenAdapter as VerificationTokenAdapter };
+}
+
+export { type AdapterUser as A, type SessionAdapter as S, type TransactionAdapter as T, type UserAdapter as U, type VerificationTokenAdapter as V, type AdapterAuditEvent as a, type AuditLogAdapter as b, type AccountAdapter as c, type AdapterAccount as d, type AdapterSession as e, type AdapterVerificationToken as f, index as i };

package/dist/index-CjEXpqaW.d.ts

@@ -0,0 +1,22 @@
+import { JWTPayload } from 'jose';
+
+interface SignOptions {
+    issuer?: string;
+    audience?: string;
+    subject?: string;
+    expiresIn?: string | number;
+    jti?: string;
+}
+declare function sign(payload: JWTPayload, secret: string | Uint8Array, opts?: SignOptions): Promise<string>;
+declare function verify<T extends JWTPayload = JWTPayload>(token: string, secret: string | Uint8Array): Promise<T>;
+declare function decode<T extends JWTPayload = JWTPayload>(token: string): T;
+
+type index_SignOptions = SignOptions;
+declare const index_decode: typeof decode;
+declare const index_sign: typeof sign;
+declare const index_verify: typeof verify;
+declare namespace index {
+  export { type index_SignOptions as SignOptions, index_decode as decode, index_sign as sign, index_verify as verify };
+}
+
+export { type SignOptions as S, decode as d, index as i, sign as s, verify as v };

package/dist/index-CotvcK_b.d.ts

@@ -0,0 +1,42 @@
+import { H as HoleauthPlugin, C as ChallengeResult, g as HoleauthHooks, w as PasswordChangeHookInput, x as PasswordResetHookInput, m as PluginContext, n as PluginCoreSurface, o as PluginEvents, p as PluginLogger, q as PluginRoute, r as PluginRouteContext, P as PluginsApi, y as RegisterHookInput, z as SessionIssueHookData, A as SessionRevokeHookData, D as SessionRotateHookData } from './index-BmYQquGs.js';
+import { H as HookRunner, P as PluginRegistry, b as buildRegistry, e as emptyRegistry, r as runOnInit } from './registry-CZhM1tEB.js';
+
+/**
+ * Identity helper that preserves the literal `id` on the plugin type so
+ * `PluginsApi<Plugins>` can index by it with full type safety.
+ *
+ * Usage:
+ *   export const twofa = () => definePlugin({
+ *     id: 'twofa' as const,
+ *     api: (ctx) => ({ setup(userId) { ... } }),
+ *   });
+ */
+declare function definePlugin<const P extends HoleauthPlugin<string, unknown>>(p: P): P;
+
+declare const index_ChallengeResult: typeof ChallengeResult;
+declare const index_HoleauthHooks: typeof HoleauthHooks;
+declare const index_HoleauthPlugin: typeof HoleauthPlugin;
+declare const index_HookRunner: typeof HookRunner;
+declare const index_PasswordChangeHookInput: typeof PasswordChangeHookInput;
+declare const index_PasswordResetHookInput: typeof PasswordResetHookInput;
+declare const index_PluginContext: typeof PluginContext;
+declare const index_PluginCoreSurface: typeof PluginCoreSurface;
+declare const index_PluginEvents: typeof PluginEvents;
+declare const index_PluginLogger: typeof PluginLogger;
+declare const index_PluginRegistry: typeof PluginRegistry;
+declare const index_PluginRoute: typeof PluginRoute;
+declare const index_PluginRouteContext: typeof PluginRouteContext;
+declare const index_PluginsApi: typeof PluginsApi;
+declare const index_RegisterHookInput: typeof RegisterHookInput;
+declare const index_SessionIssueHookData: typeof SessionIssueHookData;
+declare const index_SessionRevokeHookData: typeof SessionRevokeHookData;
+declare const index_SessionRotateHookData: typeof SessionRotateHookData;
+declare const index_buildRegistry: typeof buildRegistry;
+declare const index_definePlugin: typeof definePlugin;
+declare const index_emptyRegistry: typeof emptyRegistry;
+declare const index_runOnInit: typeof runOnInit;
+declare namespace index {
+  export { index_ChallengeResult as ChallengeResult, index_HoleauthHooks as HoleauthHooks, index_HoleauthPlugin as HoleauthPlugin, index_HookRunner as HookRunner, index_PasswordChangeHookInput as PasswordChangeHookInput, index_PasswordResetHookInput as PasswordResetHookInput, index_PluginContext as PluginContext, index_PluginCoreSurface as PluginCoreSurface, index_PluginEvents as PluginEvents, index_PluginLogger as PluginLogger, index_PluginRegistry as PluginRegistry, index_PluginRoute as PluginRoute, index_PluginRouteContext as PluginRouteContext, index_PluginsApi as PluginsApi, index_RegisterHookInput as RegisterHookInput, index_SessionIssueHookData as SessionIssueHookData, index_SessionRevokeHookData as SessionRevokeHookData, index_SessionRotateHookData as SessionRotateHookData, index_buildRegistry as buildRegistry, index_definePlugin as definePlugin, index_emptyRegistry as emptyRegistry, index_runOnInit as runOnInit };
+}
+
+export { definePlugin as d, index as i };

package/dist/index-D57PvFMN.d.ts

@@ -0,0 +1,105 @@
+import { a as HoleauthConfig, k as IssuedTokens, S as SessionData, b as HoleauthInstance } from './index-BmYQquGs.js';
+
+interface IssueInput {
+    userId: string;
+    /** Omit to start a fresh family (e.g. on a real login). */
+    familyId?: string;
+    ip?: string | null;
+    userAgent?: string | null;
+}
+/**
+ * Mint a brand new session row + JWT pair + CSRF token.
+ * Used by: fresh login, passkey login, SSO callback, 2FA verify.
+ */
+declare function issueSession(cfg: HoleauthConfig, input: IssueInput): Promise<IssuedTokens>;
+
+/**
+ * Rotate-on-use with reuse detection.
+ *
+ *  1. Decode refresh JWT → recover sid, fam, sub.
+ *  2. Hash presented token; look it up.
+ *     - If not found, the token was already rotated away → reuse! Revoke family.
+ *  3. Issue new access + refresh, rotate hash in storage atomically.
+ *
+ * Returns a fresh IssuedTokens tuple. Session id + family stay stable.
+ */
+declare function rotateRefresh(cfg: HoleauthConfig, presentedRefresh: string, meta?: {
+    ip?: string | null;
+    userAgent?: string | null;
+}): Promise<IssuedTokens>;
+
+/**
+ * Edge-compatible: verifies the access JWT only. Does not touch adapters.
+ * Use this in middleware / hot paths.
+ */
+declare function validateSession(cfg: HoleauthConfig, token: string): Promise<SessionData | null>;
+
+/** Revoke a single session by id (signout). */
+declare function revokeSession(cfg: HoleauthConfig, sessionId: string, userId?: string): Promise<void>;
+/** Revoke by presented refresh token (best-effort). */
+declare function revokeByRefresh(cfg: HoleauthConfig, refreshToken: string): Promise<void>;
+/** Global signout — all sessions for a user. */
+declare function revokeAllForUser(cfg: HoleauthConfig, userId: string): Promise<void>;
+
+/** SHA-256 → base64url. Works on Node 20+ and all Edge runtimes. */
+declare function sha256b64url(input: string): Promise<string>;
+
+interface GetSessionOrRefreshInput {
+    /** Current access token (if any). */
+    accessToken?: string | null;
+    /** Current refresh token (if any). When present, used to rotate on access miss. */
+    refreshToken?: string | null;
+    /** Request metadata, forwarded to refresh hooks/audit log. */
+    ip?: string;
+    userAgent?: string;
+}
+interface GetSessionOrRefreshResult {
+    /** Resolved session, or null if both validation and refresh failed. */
+    session: SessionData | null;
+    /** Freshly-issued token bundle when a refresh actually occurred. */
+    tokens: IssuedTokens | null;
+    /** True if this call rotated the refresh token. */
+    refreshed: boolean;
+}
+/**
+ * Validate the access token and, if invalid/missing, transparently rotate the
+ * refresh token to obtain a new session. Framework-agnostic — used by the
+ * Next.js middleware/server helpers and intended for consumption from API
+ * server middleware (tRPC, Hono, plain route handlers, …).
+ *
+ * Cookies are NOT touched here; the caller decides how to surface the new
+ * token bundle (Set-Cookie headers, in-memory store, etc.).
+ *
+ * Returns:
+ *  - `session` the resolved session (or `null`),
+ *  - `tokens` the newly-issued token bundle when a refresh occurred,
+ *  - `refreshed` whether rotation happened.
+ *
+ * @example
+ * ```ts
+ * const { session, tokens } = await getSessionOrRefresh(auth, {
+ *   accessToken: req.cookies.get('holeauth.at')?.value,
+ *   refreshToken: req.cookies.get('holeauth.rt')?.value,
+ *   ip, userAgent,
+ * });
+ * if (tokens) writeAuthCookies(auth.config, res.headers, tokens);
+ * ```
+ */
+declare function getSessionOrRefresh(instance: HoleauthInstance, input: GetSessionOrRefreshInput): Promise<GetSessionOrRefreshResult>;
+
+type index_GetSessionOrRefreshInput = GetSessionOrRefreshInput;
+type index_GetSessionOrRefreshResult = GetSessionOrRefreshResult;
+type index_IssueInput = IssueInput;
+declare const index_getSessionOrRefresh: typeof getSessionOrRefresh;
+declare const index_issueSession: typeof issueSession;
+declare const index_revokeAllForUser: typeof revokeAllForUser;
+declare const index_revokeByRefresh: typeof revokeByRefresh;
+declare const index_revokeSession: typeof revokeSession;
+declare const index_rotateRefresh: typeof rotateRefresh;
+declare const index_sha256b64url: typeof sha256b64url;
+declare const index_validateSession: typeof validateSession;
+declare namespace index {
+  export { type index_GetSessionOrRefreshInput as GetSessionOrRefreshInput, type index_GetSessionOrRefreshResult as GetSessionOrRefreshResult, type index_IssueInput as IssueInput, index_getSessionOrRefresh as getSessionOrRefresh, index_issueSession as issueSession, index_revokeAllForUser as revokeAllForUser, index_revokeByRefresh as revokeByRefresh, index_revokeSession as revokeSession, index_rotateRefresh as rotateRefresh, index_sha256b64url as sha256b64url, index_validateSession as validateSession };
+}
+
+export { type GetSessionOrRefreshInput as G, type IssueInput as I, type GetSessionOrRefreshResult as a, issueSession as b, revokeByRefresh as c, revokeSession as d, rotateRefresh as e, getSessionOrRefresh as g, index as i, revokeAllForUser as r, sha256b64url as s, validateSession as v };

package/dist/index-DRN-5E_H.d.ts

@@ -0,0 +1,26 @@
+import { a as HoleauthConfig, u as HoleauthEvent, v as HoleauthEventType } from './index-BmYQquGs.js';
+
+type Handler = (e: HoleauthEvent) => void | Promise<void>;
+/** Subscribe to an event type. Use '*' to match all events. Returns an unsubscribe fn. */
+declare function subscribe(cfg: HoleauthConfig, type: string, handler: Handler): () => void;
+declare function unsubscribe(cfg: HoleauthConfig, type: string, handler: Handler): void;
+/**
+ * emit() persists the event via the mandatory AuditLogAdapter and
+ * additionally fans out to all subscribers (typed + wildcard) plus the
+ * legacy `cfg.onEvent` hook — all fire-and-forget so business flows are
+ * never blocked by observer failures.
+ *
+ * Callers MUST await emit(): audit persistence is a hard requirement.
+ */
+declare function emit(cfg: HoleauthConfig, event: HoleauthEvent): Promise<void>;
+
+declare const index_HoleauthEvent: typeof HoleauthEvent;
+declare const index_HoleauthEventType: typeof HoleauthEventType;
+declare const index_emit: typeof emit;
+declare const index_subscribe: typeof subscribe;
+declare const index_unsubscribe: typeof unsubscribe;
+declare namespace index {
+  export { index_HoleauthEvent as HoleauthEvent, index_HoleauthEventType as HoleauthEventType, index_emit as emit, index_subscribe as subscribe, index_unsubscribe as unsubscribe };
+}
+
+export { emit as e, index as i, subscribe as s, unsubscribe as u };

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { H as HoleauthPlugin, a as HoleauthConfig, b as HoleauthInstance, P as PluginsApi } from './index-BmYQquGs.js';
+export { B as BaseProviderConfig, C as ChallengeResult, c as ConsumeInviteInput, d as ConsumeInviteResult, e as CreateInviteResult, f as HoleauthAdapters, g as HoleauthHooks, h as HoleauthSecrets, I as InviteClaims, i as InviteInput, j as InviteListEntry, k as IssuedTokens, L as LoggerOptions, O as OAuth2ProviderConfig, l as OIDCProviderConfig, m as PluginContext, n as PluginCoreSurface, o as PluginEvents, p as PluginLogger, q as PluginRoute, r as PluginRouteContext, s as ProviderConfig, R as RegistrationConfig, S as SessionData, t as SignInResult, T as TokenPolicy } from './index-BmYQquGs.js';
+export { AccountConflictError, AdapterError, CredentialsError, CsrfError, HoleauthError, InvalidTokenError, NotSupportedError, PendingChallengeError, ProviderError, RefreshReuseError, RegistrationDisabledError, SessionExpiredError } from './errors/index.js';
+export { i as jwt } from './index-CjEXpqaW.js';
+export { i as session } from './index-D57PvFMN.js';
+export { i as password } from './index-BYtkmk9_.js';
+export { i as otp } from './index-BwEvEa8-.js';
+export { i as sso } from './index-CHS-socJ.js';
+export { i as adapters } from './index-CNtnPdzk.js';
+export { i as cookies } from './index-BIXESLma.js';
+export { i as events } from './index-DRN-5E_H.js';
+export { i as flows } from './index-BbEXbI_k.js';
+export { d as definePlugin, i as plugins } from './index-CotvcK_b.js';
+import { P as PluginRegistry } from './registry-CZhM1tEB.js';
+import 'jose';
+
+/** Framework-binding helper (not part of the public API surface). */
+declare const INTERNAL_REGISTRY_KEY: symbol;
+/** Internal: retrieve the registry attached to an instance. */
+declare function getRegistry(instance: HoleauthInstance): PluginRegistry;
+/**
+ * defineHoleauth — primary factory.
+ *
+ * @example
+ * ```ts
+ * const auth = defineHoleauth({
+ *   adapters: { … },
+ *   secrets: { jwtSecret },
+ *   plugins: [twofa(), rbac({ file: './holeauth.rbac.yml' })] as const,
+ * });
+ * auth.twofa.setup(userId); // inferred
+ * auth.rbac.can(userId, 'users.edit'); // inferred
+ * ```
+ */
+declare function defineHoleauth<const Plugins extends readonly HoleauthPlugin<string, unknown>[] = []>(config: HoleauthConfig & {
+    plugins?: Plugins;
+}): HoleauthInstance & PluginsApi<Plugins>;
+
+export { HoleauthConfig, HoleauthInstance, HoleauthPlugin, INTERNAL_REGISTRY_KEY, PluginsApi, defineHoleauth, getRegistry };