@shtora/auth 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,148 @@
+export interface AuthUser {
+    readonly id: string;
+    readonly email: string;
+}
+export interface UserStore<User extends AuthUser = AuthUser> {
+    findByEmail(email: string): Promise<User | null>;
+    findById(id: string): Promise<User | null>;
+    /** Enforce normalized-email uniqueness atomically; hash the password before persistence. */
+    create(input: {
+        email: string;
+        password: string;
+    }): Promise<{
+        created: true;
+        user: User;
+    } | {
+        created: false;
+    }>;
+}
+export interface CredentialVerifier<User extends AuthUser = AuthUser> {
+    verify(input: {
+        email: string;
+        password: string;
+        user: User | null;
+    }): Promise<boolean>;
+}
+export type AuthActionTokenPurpose = "email-verification" | "password-reset";
+export interface AuthActionTokenStore extends ExpiredRecordStore {
+    /** Atomically replace any existing token for this user and purpose. */
+    create(input: {
+        purpose: AuthActionTokenPurpose;
+        userId: string;
+        tokenHash: string;
+        expiresAtMs: number;
+    }): Promise<void>;
+    /** Consume only an unexpired matching token, atomically; never return its stored hash. */
+    consume(input: {
+        purpose: AuthActionTokenPurpose;
+        tokenHash: string;
+        nowMs: number;
+    }): Promise<{
+        userId: string;
+    } | null>;
+}
+export interface AuthActionTokenDelivery {
+    /** Enqueue delivery promptly; callers must not log the bearer token. */
+    send(input: {
+        email: string;
+        token: string;
+        expiresAtMs: number;
+    }): Promise<void>;
+    tokenTtlSeconds?: number;
+}
+export interface EmailVerificationOptions<User extends AuthUser = AuthUser> extends AuthActionTokenDelivery {
+    tokens: AuthActionTokenStore;
+    isVerified(user: User): boolean;
+    markVerified(userId: string): Promise<void>;
+}
+export interface PasswordResetOptions extends AuthActionTokenDelivery {
+    tokens: AuthActionTokenStore;
+    /** Update the application's password hash; this package never hashes or stores passwords. */
+    setPassword(input: {
+        userId: string;
+        password: string;
+    }): Promise<void>;
+}
+/** id is random and non-secret; tokenHash is the cookie token digest. Timestamps are Unix epoch milliseconds. */
+export interface StoredSession {
+    readonly id: string;
+    readonly tokenHash: string;
+    readonly userId: string;
+    readonly createdAtMs: number;
+    readonly expiresAtMs: number;
+}
+export interface AuthOptions<User extends AuthUser = AuthUser> {
+    users: UserStore<User>;
+    credentials: CredentialVerifier<User>;
+    sessions: SessionStore;
+    emailPolicy?: AccessPolicy;
+    resolveClientIp?: (request: Request) => string | null | Promise<string | null>;
+    ipPolicy?: AccessPolicy;
+    rateLimiter?: AuthRateLimiter;
+    emailVerification?: EmailVerificationOptions<User>;
+    passwordReset?: PasswordResetOptions;
+    allowedHosts?: readonly string[];
+    onError?: (event: {
+        operation: string;
+        error: unknown;
+    }) => void | Promise<void>;
+    requireOrigin?: boolean;
+    basePath?: string;
+    cookieName?: string;
+    sessionTtlSeconds?: number;
+    maxRequestBytes?: number;
+}
+export interface ExpiredRecordStore {
+    /** Delete at most `limit` expired records; call periodically from a scheduled task. */
+    deleteExpired(input: {
+        nowMs: number;
+        limit: number;
+    }): Promise<void>;
+}
+export interface SessionStore extends ExpiredRecordStore {
+    create(session: StoredSession): Promise<void>;
+    findByTokenHash(tokenHash: string): Promise<StoredSession | null>;
+    deleteByTokenHash(tokenHash: string): Promise<void>;
+    listByUserId(userId: string): Promise<readonly StoredSession[]>;
+    deleteByIdForUser(id: string, userId: string): Promise<void>;
+    deleteByUserId(userId: string): Promise<void>;
+}
+export interface AuthRateLimiter {
+    check(input: {
+        action: "register" | "login" | "email-verification" | "password-reset";
+        email: string;
+        ip: string;
+    }): Promise<{
+        allowed: boolean;
+        retryAfterSeconds?: number;
+    }>;
+}
+export type AuthRequestRateLimitAction = "oidc-start" | "oidc-callback" | "webauthn-registration-options" | "webauthn-registration-verify" | "webauthn-authentication-options" | "webauthn-authentication-verify";
+export interface AuthRequestRateLimiter {
+    check(input: {
+        action: AuthRequestRateLimitAction;
+        ip: string;
+    }): Promise<{
+        allowed: boolean;
+        retryAfterSeconds?: number;
+    }>;
+}
+export interface AccessPolicy {
+    allow(input: {
+        value: string;
+        request: Request;
+    }): Promise<boolean>;
+}
+export interface AuthenticatedUser {
+    readonly id: string;
+    readonly email: string;
+}
+export interface AuthApi {
+    handle(request: Request): Promise<Response>;
+    /** Delete a bounded batch of expired sessions and action tokens from each configured store. */
+    cleanupExpired(): Promise<void>;
+    /** Rejects if a backing adapter fails; unexpected errors are observed before being rethrown. */
+    getSession(request: Request): Promise<AuthenticatedUser | null>;
+    /** Use only after an external identity protocol has been verified; creates a server-side session. */
+    createSessionResponse(request: Request, userId: string): Promise<Response>;
+}

package/dist/types.js

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

package/dist/webauthn.d.ts

@@ -0,0 +1,68 @@
+import type { WebAuthnCredential } from "@simplewebauthn/server";
+import type { AuthApi, AuthRequestRateLimiter, ExpiredRecordStore } from "./types.js";
+export type WebAuthnChallengePurpose = "registration" | "authentication";
+/** Stores must consume atomically and delete at most the requested number of expired challenges per cleanup call. */
+export interface WebAuthnChallengeStore extends ExpiredRecordStore {
+    create(challenge: {
+        id: string;
+        purpose: WebAuthnChallengePurpose;
+        userId: string | null;
+        value: string;
+        expiresAtMs: number;
+    }): Promise<void>;
+    consume(input: {
+        id: string;
+        purpose: WebAuthnChallengePurpose;
+        userId: string | null;
+        nowMs: number;
+    }): Promise<{
+        value: string;
+    } | null>;
+}
+/** The counter update must be atomic compare-and-set; create must enforce credential-ID uniqueness. */
+export interface WebAuthnCredentialStore {
+    listByUserId(userId: string): Promise<readonly WebAuthnCredential[]>;
+    findById(id: string): Promise<{
+        userId: string;
+        credential: WebAuthnCredential;
+    } | null>;
+    create(input: {
+        userId: string;
+        credential: WebAuthnCredential;
+    }): Promise<boolean>;
+    updateCounter(input: {
+        id: string;
+        expectedCounter: number;
+        newCounter: number;
+    }): Promise<boolean>;
+}
+export interface WebAuthnUser {
+    /** Stable opaque application ID, encoded as UTF-8 and limited to 64 bytes. */
+    id: string;
+    name: string;
+    displayName: string;
+}
+export interface WebAuthnOptions {
+    /** Exact origin, including scheme and port; never inferred from an incoming request. */
+    expectedOrigin: string;
+    /** Exact RP ID configured by the relying party. */
+    rpID: string;
+    rpName: string;
+    challenges: WebAuthnChallengeStore;
+    credentials: WebAuthnCredentialStore;
+    /** Return the authenticated application user for registration, or null. */
+    resolveRegistrationUser(request: Request): Promise<WebAuthnUser | null>;
+    auth: Pick<AuthApi, "createSessionResponse">;
+    resolveClientIp: (request: Request) => string | null | Promise<string | null>;
+    rateLimiter: AuthRequestRateLimiter;
+    challengeTtlMs?: number;
+    onError?(input: {
+        operation: string;
+        error: unknown;
+    }): void | Promise<void>;
+}
+/** Creates framework-neutral WebAuthn registration and authentication HTTP handlers. */
+export declare function createWebAuthn(options: WebAuthnOptions): {
+    handle(request: Request): Promise<Response>;
+    cleanupExpired(): Promise<void>;
+};

package/dist/webauthn.js

@@ -0,0 +1,302 @@
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse, } from "@simplewebauthn/server";
+const defaultChallengeTtlMs = 5 * 60 * 1000;
+const maxChallengeTtlMs = 15 * 60 * 1000;
+const maxBodyBytes = 64 * 1024;
+function json(body, status = 200, headers) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            "Cache-Control": "no-store",
+            "Content-Type": "application/json; charset=utf-8",
+            "X-Content-Type-Options": "nosniff",
+            ...Object.fromEntries(new Headers(headers)),
+        },
+    });
+}
+function reject() {
+    return json({ error: "invalid_request" }, 400);
+}
+function randomId() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function hasSameOrigin(request, expectedOrigin) {
+    const origin = request.headers.get("origin");
+    if (!origin)
+        return false;
+    try {
+        const parsed = new URL(origin);
+        return parsed.origin === origin &&
+            !parsed.username &&
+            !parsed.password &&
+            parsed.pathname === "/" &&
+            !parsed.search &&
+            !parsed.hash &&
+            origin === expectedOrigin;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJson(request) {
+    const contentLength = Number(request.headers.get("content-length"));
+    if (Number.isFinite(contentLength) && contentLength > maxBodyBytes)
+        return null;
+    const reader = request.body?.getReader();
+    if (!reader)
+        return null;
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > maxBodyBytes) {
+                await reader.cancel();
+                return null;
+            }
+            chunks.push(value);
+        }
+        const bytes = new Uint8Array(length);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        return value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function isLoopback(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return host === "localhost" || host.endsWith(".localhost") || host === "::1" || host.startsWith("127.");
+}
+async function report(options, operation, error) {
+    try {
+        await options.onError?.({ operation, error });
+    }
+    catch {
+        // Error observers must not affect the generic public result.
+    }
+}
+/** Creates framework-neutral WebAuthn registration and authentication HTTP handlers. */
+export function createWebAuthn(options) {
+    let expectedOrigin;
+    try {
+        const parsed = new URL(options.expectedOrigin);
+        const isSecureScheme = parsed.protocol === "https:";
+        const isLocalHttp = parsed.protocol === "http:" && isLoopback(parsed.hostname);
+        if (parsed.origin !== options.expectedOrigin || (!isSecureScheme && !isLocalHttp))
+            throw new TypeError();
+        const hostname = parsed.hostname.toLowerCase();
+        const rpID = options.rpID.toLowerCase();
+        if (parsed.origin !== options.expectedOrigin ||
+            (!isSecureScheme && !isLocalHttp) ||
+            !rpID ||
+            (hostname !== rpID && !hostname.endsWith(`.${rpID}`)) ||
+            !options.rpName.trim())
+            throw new TypeError();
+        expectedOrigin = parsed.origin;
+    }
+    catch {
+        throw new TypeError("expectedOrigin must be HTTPS (or localhost HTTP), rpID must match its host, and rpName must be non-empty");
+    }
+    const challengeTtlMs = options.challengeTtlMs ?? defaultChallengeTtlMs;
+    if (!Number.isSafeInteger(challengeTtlMs) || challengeTtlMs < 1_000 || challengeTtlMs > maxChallengeTtlMs) {
+        throw new RangeError("challengeTtlMs must be between 1000 and 900000");
+    }
+    async function createChallenge(purpose, userId, value) {
+        const id = randomId();
+        await options.challenges.create({
+            id,
+            purpose,
+            userId,
+            value,
+            expiresAtMs: Date.now() + challengeTtlMs,
+        });
+        return id;
+    }
+    async function registrationOptions(request) {
+        const user = await options.resolveRegistrationUser(request);
+        if (!user || !user.id || !user.name || !user.displayName)
+            return json({ error: "unauthenticated" }, 401);
+        const userID = new TextEncoder().encode(user.id);
+        if (userID.byteLength > 64)
+            throw new RangeError("WebAuthn user IDs must not exceed 64 UTF-8 bytes");
+        const existing = await options.credentials.listByUserId(user.id);
+        const publicKey = await generateRegistrationOptions({
+            rpName: options.rpName,
+            rpID: options.rpID,
+            userID,
+            userName: user.name,
+            userDisplayName: user.displayName,
+            authenticatorSelection: { residentKey: "required", userVerification: "required" },
+            excludeCredentials: existing.map(({ id, transports }) => ({ id, transports })),
+        });
+        const transactionId = await createChallenge("registration", user.id, publicKey.challenge);
+        return json({ transactionId, options: publicKey });
+    }
+    async function registrationVerify(request) {
+        const body = await readJson(request);
+        if (!body || typeof body.transactionId !== "string" || !body.response || typeof body.response !== "object")
+            return reject();
+        const user = await options.resolveRegistrationUser(request);
+        if (!user)
+            return json({ error: "unauthenticated" }, 401);
+        const transaction = await options.challenges.consume({
+            id: body.transactionId,
+            purpose: "registration",
+            userId: user.id,
+            nowMs: Date.now(),
+        });
+        if (!transaction)
+            return reject();
+        let verification;
+        try {
+            verification = await verifyRegistrationResponse({
+                response: body.response,
+                expectedChallenge: transaction.value,
+                expectedOrigin,
+                expectedRPID: options.rpID,
+                requireUserVerification: true,
+            });
+        }
+        catch {
+            return reject();
+        }
+        if (!verification.verified || !verification.registrationInfo)
+            return reject();
+        const { credential } = verification.registrationInfo;
+        if (!(await options.credentials.create({ userId: user.id, credential })))
+            return reject();
+        return json({ verified: true });
+    }
+    async function authenticationOptions() {
+        const publicKey = await generateAuthenticationOptions({
+            rpID: options.rpID,
+            userVerification: "required",
+        });
+        const transactionId = await createChallenge("authentication", null, publicKey.challenge);
+        return json({ transactionId, options: publicKey });
+    }
+    async function authenticationVerify(request) {
+        const body = await readJson(request);
+        if (!body || typeof body.transactionId !== "string" || !body.response || typeof body.response !== "object" ||
+            typeof body.response.id !== "string")
+            return reject();
+        const response = body.response;
+        const transaction = await options.challenges.consume({
+            id: body.transactionId,
+            purpose: "authentication",
+            userId: null,
+            nowMs: Date.now(),
+        });
+        if (!transaction)
+            return reject();
+        const stored = await options.credentials.findById(response.id);
+        if (!stored || stored.credential.id !== response.id)
+            return reject();
+        let verification;
+        try {
+            verification = await verifyAuthenticationResponse({
+                response,
+                expectedChallenge: transaction.value,
+                expectedOrigin,
+                expectedRPID: options.rpID,
+                credential: stored.credential,
+                requireUserVerification: true,
+            });
+        }
+        catch {
+            return reject();
+        }
+        if (!verification.verified)
+            return reject();
+        const updated = await options.credentials.updateCounter({
+            id: stored.credential.id,
+            expectedCounter: stored.credential.counter,
+            newCounter: verification.authenticationInfo.newCounter,
+        });
+        if (!updated)
+            return reject();
+        const session = await options.auth.createSessionResponse(request, stored.userId);
+        if (session.status === 200)
+            return session;
+        return json({ error: "unauthenticated" }, session.status === 403 ? 403 : 401);
+    }
+    async function handle(request) {
+        if (request.method !== "POST")
+            return json({ error: "method_not_allowed" }, 405);
+        if (!hasSameOrigin(request, expectedOrigin))
+            return json({ error: "invalid_origin" }, 403);
+        const path = new URL(request.url).pathname;
+        const routes = {
+            "/webauthn/registration/options": {
+                operation: "registration.options",
+                rateLimitAction: "webauthn-registration-options",
+                run: () => registrationOptions(request),
+            },
+            "/webauthn/registration/verify": {
+                operation: "registration.verify",
+                rateLimitAction: "webauthn-registration-verify",
+                run: () => registrationVerify(request),
+            },
+            "/webauthn/authentication/options": {
+                operation: "authentication.options",
+                rateLimitAction: "webauthn-authentication-options",
+                run: authenticationOptions,
+            },
+            "/webauthn/authentication/verify": {
+                operation: "authentication.verify",
+                rateLimitAction: "webauthn-authentication-verify",
+                run: () => authenticationVerify(request),
+            },
+        };
+        const route = routes[path];
+        if (!route)
+            return json({ error: "not_found" }, 404);
+        try {
+            const ip = await options.resolveClientIp(request);
+            const decision = ip
+                ? await options.rateLimiter.check({ action: route.rateLimitAction, ip })
+                : { allowed: false, retryAfterSeconds: 60 };
+            if (!decision.allowed) {
+                const seconds = Number.isSafeInteger(decision.retryAfterSeconds) && decision.retryAfterSeconds > 0
+                    ? decision.retryAfterSeconds
+                    : 60;
+                return json({ error: "rate_limited" }, 429, { "Retry-After": String(seconds) });
+            }
+            return await route.run();
+        }
+        catch (error) {
+            await report(options, route.operation, error);
+            return json({ error: "internal_error" }, 500);
+        }
+    }
+    return {
+        handle,
+        async cleanupExpired() {
+            try {
+                await options.challenges.deleteExpired({ nowMs: Date.now(), limit: 500 });
+            }
+            catch (error) {
+                await report(options, "challenge.cleanup", error);
+                throw error;
+            }
+        },
+    };
+}

package/migrations/0001_shtora_auth.sql

@@ -0,0 +1,39 @@
+CREATE TABLE IF NOT EXISTS shtora_sessions (
+  id TEXT PRIMARY KEY NOT NULL,
+  token_hash TEXT NOT NULL UNIQUE,
+  user_id TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL,
+  expires_at_ms INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS shtora_sessions_user_created
+  ON shtora_sessions (user_id, created_at_ms, id);
+
+CREATE TABLE IF NOT EXISTS shtora_rate_limits (
+  key_hash TEXT PRIMARY KEY NOT NULL,
+  window_start_ms INTEGER NOT NULL,
+  count INTEGER NOT NULL CHECK (count > 0)
+);
+
+CREATE TABLE IF NOT EXISTS shtora_action_tokens (
+  purpose TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  token_hash TEXT NOT NULL,
+  expires_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (purpose, token_hash)
+);
+
+CREATE INDEX IF NOT EXISTS shtora_action_tokens_expiry
+  ON shtora_action_tokens (expires_at_ms);
+CREATE INDEX IF NOT EXISTS shtora_action_tokens_user_purpose
+  ON shtora_action_tokens (purpose, user_id);
+
+-- Preferred cleanup path: schedule cleanupD1AuthState(db, { rateLimitMaxWindowSeconds }).
+-- It uses bounded batches for expired sessions/action tokens and completed rate-limit windows.
+-- Manual equivalent for rate counters:
+-- DELETE FROM shtora_rate_limits WHERE window_start_ms < :now_ms - :max_window_ms;
+-- Set :max_window_ms to the longest configured rate-limit window in milliseconds.
+-- Manual equivalent for action tokens and sessions:
+-- DELETE FROM shtora_action_tokens WHERE expires_at_ms <= :now_ms;
+-- DELETE FROM shtora_sessions WHERE expires_at_ms <= :now_ms;
+-- Apply 0002_session_expiry_index.sql and 0003_rate_limit_expiry_index.sql for cleanup indexes.

package/migrations/0002_session_expiry_index.sql

@@ -0,0 +1,2 @@
+CREATE INDEX IF NOT EXISTS shtora_sessions_expiry
+  ON shtora_sessions (expires_at_ms);

package/migrations/0003_rate_limit_expiry_index.sql

@@ -0,0 +1,2 @@
+CREATE INDEX IF NOT EXISTS shtora_rate_limits_window_start
+  ON shtora_rate_limits (window_start_ms);

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@shtora/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Framework-neutral auth handlers and session management for Next.js and Cloudflare Workers, with optional D1, OIDC, and WebAuthn adapters.",
+  "keywords": [
+    "authentication",
+    "auth",
+    "nextjs",
+    "next.js",
+    "cloudflare-workers",
+    "cloudflare-d1",
+    "workers",
+    "session-management",
+    "sessions",
+    "typescript",
+    "edge-runtime",
+    "oidc",
+    "openid-connect",
+    "webauthn",
+    "passkeys",
+    "email-verification",
+    "password-reset"
+  ],
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "import": "./dist/cloudflare.js"
+    },
+    "./oidc": {
+      "types": "./dist/oidc.d.ts",
+      "import": "./dist/oidc.js"
+    },
+    "./webauthn": {
+      "types": "./dist/webauthn.d.ts",
+      "import": "./dist/webauthn.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orgShtora-1/auth.git"
+  },
+  "homepage": "https://github.com/orgShtora-1/auth#readme",
+  "bugs": {
+    "url": "https://github.com/orgShtora-1/auth/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@simplewebauthn/server": ">=14.0.3 <15",
+    "openid-client": ">=6 <7"
+  },
+  "peerDependenciesMeta": {
+    "@simplewebauthn/server": {
+      "optional": true
+    },
+    "openid-client": {
+      "optional": true
+    }
+  },
+  "files": ["dist", "migrations"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@simplewebauthn/server": "^14.0.3",
+    "@types/bun": "latest",
+    "openid-client": "^6.8.1",
+    "typescript": "^7.0.2"
+  }
+}