@evcraddock/slug-auth 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @evcraddock/slug-auth
+
+Reusable Slugkit authentication primitives and storage interfaces.
+
+## Exports
+
+- Token helpers: `generateToken`, `hashToken`, `generateRawApiKey`, `hashApiKey`, and `readApiKeyPrefix`.
+- API key helpers: `VIEWER_API_KEY_SCOPES`, `normalizeApiKeyScopes`, `isApiKeyAuthorizedForOperation`, and `operationToScope`.
+- Magic-link helpers: `normalizeEmail`, `normalizeRedirectPath`, `createLoginUrl`, `createMagicLinkDelivery`, `readSmtpConfig`, and `createMagicLinkMessage`.
+- Passkey helpers: `resolveWebAuthnOrigin`, `createRelyingPartyFromOrigins`, `normalizePasskeyName`, `normalizeTransports`, `encodeBase64Url`, `decodeBase64Url`, and `parseStringArrayJson`.
+- Logging helpers: `consoleAuthLogger`, `consoleApiLogger`, `silentAuthLogger`, and `logCaughtError`.
+- Storage interfaces: `ApiKeyRepository`, `SiteUserRepository`, `SessionRepository`, `MagicLinkRepository`, and `PasskeyRepository`.
+
+## Site-owned storage
+
+This package intentionally does not own generated-site databases. Generated sites keep local wrapper modules and migrations, then use package helpers for the security-sensitive primitives that should receive patch updates.
+
+## Security patch guidance
+
+Generated sites should apply patch releases of `@evcraddock/slug-auth` promptly. Patch releases may include token handling, API-key verification, SMTP delivery, passkey/WebAuthn, and logging hardening fixes without requiring a template rewrite.

package/dist/index.d.ts

@@ -0,0 +1,172 @@
+import type { SendMailOptions, Transporter } from "nodemailer";
+export type AuthLogLevel = "info" | "warn";
+export interface AuthLogEntry {
+    level: AuthLogLevel;
+    message: string;
+    context?: Record<string, string>;
+}
+export type AuthLogger = (entry: AuthLogEntry) => void;
+export type SiteUserRole = "admin" | "viewer";
+export interface SiteUserRecord {
+    id: string;
+    email: string;
+    displayName: string | null;
+    roles: SiteUserRole[];
+    createdAt: string;
+    updatedAt: string;
+    deactivatedAt: string | null;
+}
+export interface AuthSessionRecord {
+    id: string;
+    email: string;
+    expiresAt: string;
+    createdAt: string;
+}
+export declare const VIEWER_API_KEY_SCOPES: readonly ["posts:read", "sources:read", "contacts:read"];
+export type ApiKeyScope = (typeof VIEWER_API_KEY_SCOPES)[number];
+export interface ApiKeyRecord {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    scopes: ApiKeyScope[];
+    siteUserId: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+}
+export interface CreatedApiKey {
+    apiKey: ApiKeyRecord;
+    rawKey: string;
+}
+export interface VerifiedApiKey {
+    valid: true;
+    apiKey: ApiKeyRecord;
+}
+export interface InvalidApiKey {
+    valid: false;
+}
+export type ApiKeyVerificationResult = VerifiedApiKey | InvalidApiKey;
+export type ApiKeyValidator = (rawKey: string, operation?: string, method?: string) => boolean | Promise<boolean>;
+export interface ApiKeyRepository {
+    create(input: {
+        name: string;
+        siteUserId: string | null;
+        scopes: ApiKeyScope[];
+    }): CreatedApiKey;
+    list(input?: {
+        siteUserId?: string;
+    }): ApiKeyRecord[];
+    verify(rawKey: string): ApiKeyVerificationResult;
+    revoke(id: string, input?: {
+        siteUserId?: string;
+    }): boolean;
+}
+export interface SiteUserRepository {
+    list(): SiteUserRecord[];
+    getByEmail(email: string): SiteUserRecord | null;
+    isActive(email: string): boolean;
+    hasRole(email: string, role: SiteUserRole): boolean;
+}
+export interface SessionRepository {
+    create(email: string, now?: Date): AuthSessionRecord;
+    get(sessionId: string | undefined, now?: Date): AuthSessionRecord | null;
+    delete(sessionId: string | undefined): void;
+}
+export interface MagicLinkRepository {
+    create(input: {
+        id: string;
+        email: string;
+        tokenHash: string;
+        redirectPath: string | null;
+        expiresAt: string;
+        createdAt: string;
+    }): void;
+    verify(input: {
+        tokenHash: string;
+        now: Date;
+    }): MagicLinkVerificationResult;
+}
+export interface PasskeyRepository {
+    list(email?: string): AdminPasskeyRecord[];
+    getByCredentialId(credentialId: string): AdminPasskeyRecord | null;
+    delete(id: string, email: string): void;
+}
+export interface AdminPasskeyRecord {
+    id: string;
+    email: string;
+    name: string;
+    credentialId: string;
+    credentialPublicKey: string;
+    counter: number;
+    transports: string[];
+    credentialDeviceType: string;
+    credentialBackedUp: boolean;
+    aaguid: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+export interface MagicLinkVerificationSuccess {
+    valid: true;
+    email: string;
+    redirectPath: string | null;
+}
+export interface MagicLinkVerificationFailure {
+    valid: false;
+}
+export type MagicLinkVerificationResult = MagicLinkVerificationSuccess | MagicLinkVerificationFailure;
+export interface MagicLinkDeliveryInput {
+    email: string;
+    loginUrl: string;
+}
+export type MagicLinkDelivery = (input: MagicLinkDeliveryInput) => Promise<void> | void;
+export interface SmtpConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    auth: {
+        user: string;
+        pass: string;
+    } | undefined;
+    fromEmail: string;
+    fromName: string | undefined;
+}
+export interface CreateMagicLinkDeliveryOptions {
+    createTransport?: (config: SmtpConfig) => Pick<Transporter, "sendMail">;
+}
+export declare class MagicLinkDeliveryNotConfiguredError extends Error {
+    constructor(message?: string);
+}
+export declare const API_KEY_DISPLAY_PREFIX_LENGTH = 12;
+export declare function generateToken(byteLength?: number): string;
+export declare function hashToken(token: string): string;
+export declare function generateRawApiKey(): string;
+export declare function hashApiKey(rawKey: string): string;
+export declare function readApiKeyPrefix(rawKey: string): string;
+export declare function normalizeApiKeyScopes(scopes: readonly unknown[]): ApiKeyScope[];
+export declare function isApiKeyScope(value: unknown): value is ApiKeyScope;
+export declare function isApiKeyAuthorizedForOperation(apiKey: Pick<ApiKeyRecord, "scopes">, operation: string | undefined): boolean;
+export declare function operationToScope(operation: string | undefined): ApiKeyScope | null;
+export declare function createLoginUrl(requestUrl: string, token: string, redirectPath: string | null): string;
+export declare function normalizeEmail(email: string): string;
+export declare function normalizeRedirectPath(path: string | undefined): string | null;
+export declare function createMagicLinkDelivery(environment?: Record<string, string | undefined>, options?: CreateMagicLinkDeliveryOptions): MagicLinkDelivery;
+export declare function readSmtpConfig(environment: Record<string, string | undefined>): SmtpConfig;
+export declare function createMagicLinkMessage(config: SmtpConfig, email: string, loginUrl: string): SendMailOptions;
+export declare function resolveWebAuthnOrigin(configuredSiteUrl: string, requestUrl: string): string;
+export declare function createRelyingPartyFromOrigins(configuredSiteUrl: string, requestUrl: string): {
+    origin: string;
+    rpID: string;
+};
+export declare function normalizePasskeyName(name: string | undefined): string;
+export declare function normalizeTransports(transports: string[]): ("ble" | "cable" | "hybrid" | "internal" | "nfc" | "smart-card" | "usb")[];
+export declare function encodeBase64Url(value: Uint8Array): string;
+export declare function decodeBase64Url(value: string): Uint8Array<ArrayBuffer>;
+export declare function parseStringArrayJson(value: string): string[];
+export declare const consoleAuthLogger: AuthLogger;
+export declare const consoleApiLogger: AuthLogger;
+export declare const silentAuthLogger: AuthLogger;
+export declare function logCaughtError(logger: AuthLogger, input: {
+    message: string;
+    error: unknown;
+    context?: Record<string, string | undefined>;
+}): void;

package/dist/index.js

@@ -0,0 +1,299 @@
+import { createHash, randomBytes } from "node:crypto";
+import nodemailer from "nodemailer";
+export const VIEWER_API_KEY_SCOPES = ["posts:read", "sources:read", "contacts:read"];
+export class MagicLinkDeliveryNotConfiguredError extends Error {
+    constructor(message = "Magic link delivery is not configured") {
+        super(message);
+    }
+}
+const RAW_KEY_PREFIX = "slug_";
+const RAW_KEY_RANDOM_BYTES = 32;
+export const API_KEY_DISPLAY_PREFIX_LENGTH = 12;
+export function generateToken(byteLength = 32) {
+    return randomBytes(byteLength).toString("base64url");
+}
+export function hashToken(token) {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+export function generateRawApiKey() {
+    return `${RAW_KEY_PREFIX}${randomBytes(RAW_KEY_RANDOM_BYTES).toString("base64url")}`;
+}
+export function hashApiKey(rawKey) {
+    return hashToken(rawKey);
+}
+export function readApiKeyPrefix(rawKey) {
+    return rawKey.slice(0, API_KEY_DISPLAY_PREFIX_LENGTH);
+}
+export function normalizeApiKeyScopes(scopes) {
+    const normalized = [];
+    for (const scope of scopes) {
+        if (isApiKeyScope(scope) && !normalized.includes(scope))
+            normalized.push(scope);
+    }
+    return normalized;
+}
+export function isApiKeyScope(value) {
+    return typeof value === "string" && VIEWER_API_KEY_SCOPES.includes(value);
+}
+export function isApiKeyAuthorizedForOperation(apiKey, operation) {
+    if (apiKey.scopes.length === 0)
+        return true;
+    const requiredScope = operationToScope(operation);
+    return requiredScope !== null && apiKey.scopes.includes(requiredScope);
+}
+export function operationToScope(operation) {
+    switch (operation) {
+        case "posts.list":
+        case "posts.get":
+            return "posts:read";
+        case "sources.list":
+        case "sources.get":
+            return "sources:read";
+        case "contacts.list":
+        case "contacts.get":
+            return "contacts:read";
+        default:
+            return null;
+    }
+}
+export function createLoginUrl(requestUrl, token, redirectPath) {
+    const url = new URL("/login/verify", requestUrl);
+    url.searchParams.set("token", token);
+    if (redirectPath !== null) {
+        url.searchParams.set("redirect", redirectPath);
+    }
+    return url.toString();
+}
+export function normalizeEmail(email) {
+    return email.trim().toLowerCase();
+}
+export function normalizeRedirectPath(path) {
+    if (path === undefined || !path.startsWith("/") || path.startsWith("//")) {
+        return null;
+    }
+    return path;
+}
+export function createMagicLinkDelivery(environment = process.env, options = {}) {
+    const devMode = isDevDeliveryMode(environment);
+    if (devMode) {
+        return ({ email, loginUrl }) => {
+            console.info("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+            console.info(`Magic link for ${email}:`);
+            console.info(loginUrl);
+            console.info("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+        };
+    }
+    const config = readSmtpConfig(environment);
+    const transport = options.createTransport?.(config) ?? createNodemailerTransport(config);
+    return async ({ email, loginUrl }) => {
+        const message = createMagicLinkMessage(config, email, loginUrl);
+        await transport.sendMail(message);
+    };
+}
+export function readSmtpConfig(environment) {
+    const host = readRequiredEnv(environment, "SMTP_HOST");
+    const port = readPort(environment.SMTP_PORT);
+    const username = readOptionalEnv(environment.SMTP_USERNAME);
+    const password = readOptionalEnv(environment.SMTP_PASSWORD);
+    const fromEmail = readRequiredEnv(environment, "SMTP_FROM_EMAIL");
+    const fromName = readOptionalEnv(environment.SMTP_FROM_NAME);
+    const secure = readBooleanEnv(environment.SMTP_SECURE, port === 465, "SMTP_SECURE");
+    if ((username === undefined) !== (password === undefined)) {
+        throw new MagicLinkDeliveryNotConfiguredError("SMTP_USERNAME and SMTP_PASSWORD must be configured together");
+    }
+    return {
+        host,
+        port,
+        secure,
+        auth: username === undefined ? undefined : { user: username, pass: password ?? "" },
+        fromEmail,
+        fromName,
+    };
+}
+export function createMagicLinkMessage(config, email, loginUrl) {
+    const from = formatSender(config);
+    const subject = "Your Slugkit sign-in link";
+    const text = [
+        "Use this link to sign in to your Slugkit site:",
+        "",
+        loginUrl,
+        "",
+        "This link expires in 15 minutes. If you did not request it, you can ignore this email.",
+    ].join("\n");
+    const html = `<p>Use this link to sign in to your Slugkit site:</p><p><a href="${escapeHtml(loginUrl)}">Sign in</a></p><p>This link expires in 15 minutes. If you did not request it, you can ignore this email.</p>`;
+    return { from, to: email, subject, text, html };
+}
+export function resolveWebAuthnOrigin(configuredSiteUrl, requestUrl) {
+    const requestOrigin = new URL(requestUrl).origin;
+    const configuredOrigin = readConfiguredWebAuthnOrigin(configuredSiteUrl);
+    if (configuredOrigin === null)
+        return requestOrigin;
+    if (isLocalhostOrigin(configuredOrigin)) {
+        return isLocalhostOrigin(requestOrigin) ? configuredOrigin : requestOrigin;
+    }
+    return configuredOrigin;
+}
+export function createRelyingPartyFromOrigins(configuredSiteUrl, requestUrl) {
+    const origin = resolveWebAuthnOrigin(configuredSiteUrl, requestUrl);
+    const url = new URL(origin);
+    return { origin, rpID: url.hostname };
+}
+export function normalizePasskeyName(name) {
+    const trimmed = name?.trim() ?? "";
+    return trimmed === "" ? "Passkey" : trimmed;
+}
+export function normalizeTransports(transports) {
+    return transports.filter((transport) => ["ble", "cable", "hybrid", "internal", "nfc", "smart-card", "usb"].includes(transport));
+}
+export function encodeBase64Url(value) {
+    return Buffer.from(value).toString("base64url");
+}
+export function decodeBase64Url(value) {
+    const buffer = Buffer.from(value, "base64url");
+    const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    return new Uint8Array(arrayBuffer);
+}
+export function parseStringArrayJson(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed)
+            ? parsed.filter((item) => typeof item === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+export const consoleAuthLogger = (entry) => {
+    writeConsoleLog("slugkit auth", entry);
+};
+export const consoleApiLogger = (entry) => {
+    writeConsoleLog("slugkit api", entry);
+};
+export const silentAuthLogger = () => { };
+export function logCaughtError(logger, input) {
+    const errorContext = serializeCaughtError(input.error);
+    logger({
+        level: "warn",
+        message: input.message,
+        context: {
+            ...filterLogContext(input.context),
+            ...errorContext,
+        },
+    });
+}
+function isDevDeliveryMode(environment) {
+    if (environment.AUTH_DEV_MODE === "true")
+        return true;
+    if (environment.AUTH_DEV_MODE === "false")
+        return false;
+    return environment.NODE_ENV !== "production";
+}
+function createNodemailerTransport(config) {
+    return nodemailer.createTransport({
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+        auth: config.auth,
+    });
+}
+function formatSender(config) {
+    if (config.fromName === undefined)
+        return config.fromEmail;
+    return `${quoteDisplayName(config.fromName)} <${config.fromEmail}>`;
+}
+function quoteDisplayName(value) {
+    return `"${value.replace(/["\\]/gu, "\\$&")}"`;
+}
+function readRequiredEnv(environment, name) {
+    const value = readOptionalEnv(environment[name]);
+    if (value === undefined) {
+        throw new MagicLinkDeliveryNotConfiguredError(`${name} is required when AUTH_DEV_MODE is false`);
+    }
+    return value;
+}
+function readOptionalEnv(value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    return value.trim();
+}
+function readPort(value) {
+    const portText = readOptionalEnv(value);
+    if (portText === undefined)
+        return 587;
+    const port = Number(portText);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new MagicLinkDeliveryNotConfiguredError("SMTP_PORT must be a valid TCP port");
+    }
+    return port;
+}
+function readBooleanEnv(value, defaultValue, name) {
+    const normalized = readOptionalEnv(value)?.toLowerCase();
+    if (normalized === undefined)
+        return defaultValue;
+    if (["true", "1", "yes", "on"].includes(normalized))
+        return true;
+    if (["false", "0", "no", "off"].includes(normalized))
+        return false;
+    throw new MagicLinkDeliveryNotConfiguredError(`${name} must be true or false`);
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"]/gu, (character) => {
+        switch (character) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            default:
+                return character;
+        }
+    });
+}
+function readConfiguredWebAuthnOrigin(configuredSiteUrl) {
+    try {
+        const url = new URL(configuredSiteUrl);
+        if (url.protocol !== "https:")
+            return null;
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
+function isLocalhostOrigin(origin) {
+    try {
+        const hostname = new URL(origin).hostname.toLowerCase();
+        return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+    }
+    catch {
+        return false;
+    }
+}
+function writeConsoleLog(prefix, entry) {
+    const context = entry.context === undefined ? "" : ` ${JSON.stringify(entry.context)}`;
+    const line = `${prefix}: ${entry.message}${context}`;
+    if (entry.level === "warn") {
+        console.warn(line);
+        return;
+    }
+    console.info(line);
+}
+function serializeCaughtError(error) {
+    if (error instanceof Error) {
+        return {
+            errorName: error.name,
+            errorMessage: error.message,
+            errorStack: error.stack ?? error.message,
+        };
+    }
+    return { errorMessage: String(error) };
+}
+function filterLogContext(context) {
+    if (context === undefined)
+        return {};
+    return Object.fromEntries(Object.entries(context).filter((entry) => entry[1] !== undefined));
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@evcraddock/slug-auth",
+  "version": "0.1.0",
+  "description": "Reusable Slugkit authentication primitives and interfaces.",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --config ../../vitest.config.ts src",
+    "test:watch": "vitest --config ../../vitest.config.ts src"
+  },
+  "dependencies": {
+    "@simplewebauthn/server": "^13.3.1",
+    "nodemailer": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^8.0.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.6"
+  }
+}