@hodela/site 0.0.0-stage → 0.1.0

package/dist/access.d.ts

@@ -0,0 +1,28 @@
+export type AccessConfig = {
+    pinHash?: string;
+    ipLimit?: {
+        mode: "whitelist" | "blacklist";
+        entries: string[];
+    };
+    blockBots?: boolean;
+    showBadge: boolean;
+};
+/** Đọc binding HODELA_ACCESS. Thiếu hoặc sai định dạng thì không áp dụng gì (không bao giờ ném lỗi). */
+export declare function parseAccessConfig(raw: unknown): AccessConfig;
+type ParsedIp = {
+    value: bigint;
+    bits: 32 | 128;
+};
+export declare function parseIp(text: string): ParsedIp | null;
+export declare function ipMatches(clientIp: string, entries: string[]): boolean;
+/** true nếu IP bị chặn theo danh sách. IP không xác định được: danh sách cho phép chặn, danh sách chặn cho qua. */
+export declare function isIpBlocked(clientIp: string | null, limit: NonNullable<AccessConfig["ipLimit"]>): boolean;
+export declare function isBotUserAgent(userAgent: string | null): boolean;
+export declare function sha256Hex(text: string): Promise<string>;
+/**
+ * Trả về phản hồi chặn (403/401/429/303) hoặc null nếu cho qua. Thứ tự: IP, bot, PIN.
+ * `secret` là HODELA_SESSION_SECRET dùng ký cookie PIN.
+ */
+export declare function enforceAccess(request: Request, config: AccessConfig, secret: string): Promise<Response | null>;
+export declare function badgeHtml(config: AccessConfig): string;
+export {};

package/dist/access.js

@@ -0,0 +1,236 @@
+// Truy cập vào website đã xuất bản, do chủ web bật trong Cài đặt: PIN, danh sách IP, chặn bot, badge Hodela.
+// Nền tảng đưa cấu hình vào binding HODELA_ACCESS (JSON) và IP khách vào header x-hodela-client-ip.
+// Chỉ áp dụng khi HODELA_ENV=production (bản xem trước dành cho chủ web). Gọi từ src/server.ts.
+//
+// File này do Hodela quản lý (cùng src/server.ts), đừng sửa.
+const PIN_PATH = "/__hodela/pin";
+const PIN_COOKIE = "hodela_pin";
+const PIN_COOKIE_MAX_AGE = 60 * 60 * 24 * 30;
+const MAX_PIN_FAILURES = 5;
+const PIN_LOCK_MS = 60_000;
+/** Đọc binding HODELA_ACCESS. Thiếu hoặc sai định dạng thì không áp dụng gì (không bao giờ ném lỗi). */
+export function parseAccessConfig(raw) {
+    const out = { showBadge: false };
+    if (typeof raw !== "string" || raw === "")
+        return out;
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return out;
+    }
+    if (!json || typeof json !== "object")
+        return out;
+    const o = json;
+    if (typeof o["pinHash"] === "string" && /^[0-9a-f]{64}$/.test(o["pinHash"]))
+        out.pinHash = o["pinHash"];
+    const ip = o["ipLimit"];
+    if (ip && (ip.mode === "whitelist" || ip.mode === "blacklist") && Array.isArray(ip.entries)) {
+        const entries = ip.entries.filter((e) => typeof e === "string" && parseCidr(e) !== null);
+        if (entries.length > 0)
+            out.ipLimit = { mode: ip.mode, entries };
+    }
+    if (o["blockBots"] === true)
+        out.blockBots = true;
+    out.showBadge = o["showBadge"] === true;
+    return out;
+}
+function parseIpv4(text) {
+    const parts = text.split(".");
+    if (parts.length !== 4)
+        return null;
+    let value = 0n;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return null;
+        const n = Number(part);
+        if (n > 255)
+            return null;
+        value = (value << 8n) | BigInt(n);
+    }
+    return value;
+}
+function parseIpv6(text) {
+    if (!/^[0-9a-fA-F:.]+$/.test(text) || !text.includes(":"))
+        return null;
+    let head = text;
+    let tail4 = null;
+    const lastColon = text.lastIndexOf(":");
+    if (text.slice(lastColon + 1).includes(".")) {
+        tail4 = parseIpv4(text.slice(lastColon + 1));
+        if (tail4 === null)
+            return null;
+        head = `${text.slice(0, lastColon + 1)}0:0`;
+    }
+    const halves = head.split("::");
+    if (halves.length > 2)
+        return null;
+    const toGroups = (s) => (s === "" ? [] : s.split(":"));
+    const left = toGroups(halves[0] ?? "");
+    const right = halves.length === 2 ? toGroups(halves[1] ?? "") : [];
+    const missing = 8 - left.length - right.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0)
+        return null;
+    const groups = [...left, ...Array(halves.length === 2 ? missing : 0).fill("0"), ...right];
+    if (groups.length !== 8)
+        return null;
+    let value = 0n;
+    for (const g of groups) {
+        if (!/^[0-9a-fA-F]{1,4}$/.test(g))
+            return null;
+        value = (value << 16n) | BigInt(parseInt(g, 16));
+    }
+    if (tail4 !== null)
+        value = (value & ~0xffffffffn) | tail4;
+    return value;
+}
+export function parseIp(text) {
+    const t = text.trim();
+    const v4 = parseIpv4(t);
+    if (v4 !== null)
+        return { value: v4, bits: 32 };
+    const v6 = parseIpv6(t);
+    if (v6 === null)
+        return null;
+    // ::ffff:a.b.c.d là IPv4 viết dạng IPv6.
+    if (v6 >> 32n === 0xffffn)
+        return { value: v6 & 0xffffffffn, bits: 32 };
+    return { value: v6, bits: 128 };
+}
+function parseCidr(entry) {
+    const [addr = "", rawPrefix, ...rest] = entry.trim().split("/");
+    if (rest.length > 0)
+        return null;
+    const ip = parseIp(addr);
+    if (!ip)
+        return null;
+    if (rawPrefix === undefined)
+        return { ip, prefix: ip.bits };
+    if (!/^\d{1,3}$/.test(rawPrefix))
+        return null;
+    const prefix = Number(rawPrefix);
+    if (prefix > ip.bits)
+        return null;
+    return { ip, prefix };
+}
+export function ipMatches(clientIp, entries) {
+    const client = parseIp(clientIp);
+    if (!client)
+        return false;
+    for (const entry of entries) {
+        const cidr = parseCidr(entry);
+        if (!cidr || cidr.ip.bits !== client.bits)
+            continue;
+        const shift = BigInt(cidr.ip.bits - cidr.prefix);
+        if (client.value >> shift === cidr.ip.value >> shift)
+            return true;
+    }
+    return false;
+}
+/** true nếu IP bị chặn theo danh sách. IP không xác định được: danh sách cho phép chặn, danh sách chặn cho qua. */
+export function isIpBlocked(clientIp, limit) {
+    const listed = clientIp ? ipMatches(clientIp, limit.entries) : false;
+    return limit.mode === "whitelist" ? !listed : listed;
+}
+// --- Bot --------------------------------------------------------------------------------------
+const BOT_UA = /bot\b|bot[\/ ;)_-]|crawl|spider|slurp|scrap|curl\/|wget|python-requests|python-urllib|aiohttp|httpclient|go-http-client|java\/|libwww|okhttp|axios|node-fetch|undici|headless|phantomjs|selenium|puppeteer|playwright/i;
+export function isBotUserAgent(userAgent) {
+    if (!userAgent || userAgent.trim() === "")
+        return true;
+    return BOT_UA.test(userAgent);
+}
+// --- PIN --------------------------------------------------------------------------------------
+const encoder = new TextEncoder();
+function toHex(buffer) {
+    return [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+export async function sha256Hex(text) {
+    return toHex(await crypto.subtle.digest("SHA-256", encoder.encode(text)));
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** Giá trị cookie đã mở khóa: gắn với PIN hiện tại, đổi PIN thì mọi cookie cũ mất hiệu lực. */
+async function pinCookieValue(pinHash, secret) {
+    const key = await crypto.subtle.importKey("raw", encoder.encode(secret || "hodela"), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return toHex(await crypto.subtle.sign("HMAC", key, encoder.encode(`pin:${pinHash}`)));
+}
+function readCookie(request, name) {
+    const header = request.headers.get("cookie");
+    if (!header)
+        return null;
+    for (const part of header.split(";")) {
+        const index = part.indexOf("=");
+        if (index > 0 && part.slice(0, index).trim() === name)
+            return part.slice(index + 1).trim();
+    }
+    return null;
+}
+const failures = new Map();
+function safeNext(value) {
+    return value && value.startsWith("/") && !value.startsWith("//") && !value.startsWith("/\\") ? value : "/";
+}
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+function pinPage(next, error, status) {
+    const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="robots" content="noindex"><title>Protected website</title><style>body{margin:0;min-height:100vh;display:grid;place-items:center;font:16px/1.5 system-ui,sans-serif;background:#f6f6f4;color:#161616}form{width:min(92vw,20rem);padding:1.5rem;border-radius:12px;background:#fff;box-shadow:0 1px 3px rgba(0,0,0,.12)}h1{margin:0 0 .25rem;font-size:1.1rem}p{margin:0 0 1rem;color:#555;font-size:.9rem}input{box-sizing:border-box;width:100%;padding:.6rem .75rem;border:1px solid #bbb;border-radius:8px;font:inherit;letter-spacing:.3em;text-align:center}button{margin-top:.75rem;width:100%;padding:.6rem;border:0;border-radius:8px;background:#161616;color:#fff;font:inherit;cursor:pointer}.err{margin:.5rem 0 0;color:#b00020;font-size:.85rem}</style></head><body><form method="post" action="${PIN_PATH}"><h1>This website is protected</h1><p>Enter the PIN to continue.</p><input name="pin" type="password" inputmode="numeric" autocomplete="off" autofocus required maxlength="8" aria-label="PIN"><input type="hidden" name="next" value="${escapeHtml(next)}"><button type="submit">Continue</button>${error ? `<p class="err" role="alert">${escapeHtml(error)}</p>` : ""}</form></body></html>`;
+    return new Response(body, { status, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } });
+}
+async function handlePinSubmit(request, config, secret, clientIp) {
+    const form = await request.formData().catch(() => null);
+    const next = safeNext(typeof form?.get("next") === "string" ? form?.get("next") : null);
+    const key = clientIp ?? "unknown";
+    const state = failures.get(key);
+    const now = Date.now();
+    if (state && state.lockedUntil > now)
+        return pinPage(next, "Too many attempts. Try again in a minute.", 429);
+    const pin = typeof form?.get("pin") === "string" ? (form?.get("pin")).trim() : "";
+    const ok = /^\d{4,8}$/.test(pin) && timingSafeEqual(await sha256Hex(pin), config.pinHash ?? "");
+    if (!ok) {
+        const count = (state && state.lockedUntil !== 0 && state.lockedUntil <= now ? 0 : (state?.count ?? 0)) + 1;
+        failures.set(key, count >= MAX_PIN_FAILURES ? { count: 0, lockedUntil: now + PIN_LOCK_MS } : { count, lockedUntil: 0 });
+        return pinPage(next, "Incorrect PIN.", 401);
+    }
+    failures.delete(key);
+    const secure = new URL(request.url).protocol === "https:" ? "; Secure" : "";
+    const cookie = `${PIN_COOKIE}=${await pinCookieValue(config.pinHash ?? "", secret)}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${PIN_COOKIE_MAX_AGE}${secure}`;
+    return new Response(null, { status: 303, headers: { location: next, "set-cookie": cookie, "cache-control": "no-store" } });
+}
+/**
+ * Trả về phản hồi chặn (403/401/429/303) hoặc null nếu cho qua. Thứ tự: IP, bot, PIN.
+ * `secret` là HODELA_SESSION_SECRET dùng ký cookie PIN.
+ */
+export async function enforceAccess(request, config, secret) {
+    const clientIp = request.headers.get("x-hodela-client-ip");
+    if (config.ipLimit && isIpBlocked(clientIp, config.ipLimit)) {
+        return new Response("Forbidden", { status: 403, headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" } });
+    }
+    const url = new URL(request.url);
+    if (config.blockBots && url.pathname !== "/robots.txt" && isBotUserAgent(request.headers.get("user-agent"))) {
+        return new Response("Forbidden", { status: 403, headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" } });
+    }
+    if (!config.pinHash)
+        return null;
+    if (url.pathname === PIN_PATH && request.method === "POST")
+        return handlePinSubmit(request, config, secret, clientIp);
+    const cookie = readCookie(request, PIN_COOKIE);
+    if (cookie && timingSafeEqual(cookie, await pinCookieValue(config.pinHash, secret)))
+        return null;
+    const wantsHtml = request.method === "GET" && (request.headers.get("accept") ?? "").includes("text/html");
+    if (wantsHtml)
+        return pinPage(`${url.pathname}${url.search}`, null, 401);
+    return new Response("PIN required", { status: 401, headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" } });
+}
+// --- Badge ------------------------------------------------------------------------------------
+// Huy hiệu "♥ Built with" + logo Hodela (SVG nội tuyến, tô bằng màu chữ); aria-label cho trình đọc màn hình.
+const BADGE_HTML = '<a href="https://hodela.com/?utm_source=published_site&amp;utm_medium=badge&amp;utm_campaign=built_with_hodela" target="_blank" rel="noopener noreferrer" data-hodela-badge="" aria-label="Built with Hodela" style="position:fixed;z-index:2147483646;right:12px;bottom:12px;display:inline-flex;align-items:center;gap:5px;padding:6px 10px;border-radius:8px;font:12px/1.2 system-ui,sans-serif;background:rgba(15,23,42,.88);color:#fff;text-decoration:none;box-shadow:0 2px 8px rgba(0,0,0,.2)"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="12" height="12" fill="#fb7185" aria-hidden="true" style="display:block;flex:none"><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/></svg><span>Built with</span><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 121.5 26.35" aria-hidden="true" style="display:block;flex:none;height:10px;width:auto"><g transform="translate(-2.065,0)"><path fill="currentColor" d="M7.42 25L2.94 25Q2.56 25 2.31 24.74Q2.07 24.48 2.07 24.13L2.07 24.13L2.07 1.02Q2.07 0.64 2.31 0.39Q2.56 0.15 2.94 0.15L2.94 0.15L7.42 0.15Q7.81 0.15 8.05 0.39Q8.29 0.64 8.29 1.02L8.29 1.02L8.29 8.83Q9.24 7.74 10.62 7.10Q12.01 6.45 13.83 6.45L13.83 6.45Q15.86 6.45 17.45 7.36Q19.04 8.27 19.95 10.02Q20.86 11.77 20.86 14.36L20.86 14.36L20.86 24.13Q20.86 24.48 20.62 24.74Q20.37 25 19.99 25L19.99 25L15.47 25Q15.12 25 14.86 24.74Q14.60 24.48 14.60 24.13L14.60 24.13L14.60 14.57Q14.60 12.92 13.81 12.03Q13.02 11.14 11.52 11.14L11.52 11.14Q10.05 11.14 9.17 12.03Q8.29 12.92 8.29 14.57L8.29 14.57L8.29 24.13Q8.29 24.48 8.05 24.74Q7.81 25 7.42 25L7.42 25ZM32.38 25.35L32.38 25.35Q29.44 25.35 27.42 24.41Q25.41 23.46 24.34 21.69Q23.28 19.93 23.14 17.48L23.14 17.48Q23.10 16.77 23.10 15.88Q23.10 14.99 23.14 14.32L23.14 14.32Q23.28 11.84 24.40 10.09Q25.52 8.34 27.53 7.39Q29.54 6.45 32.38 6.45L32.38 6.45Q35.25 6.45 37.26 7.39Q39.27 8.34 40.39 10.09Q41.51 11.84 41.65 14.32L41.65 14.32Q41.69 14.99 41.69 15.88Q41.69 16.77 41.65 17.48L41.65 17.48Q41.51 19.93 40.44 21.69Q39.38 23.46 37.36 24.41Q35.35 25.35 32.38 25.35ZM32.38 21.08L32.38 21.08Q33.95 21.08 34.67 20.13Q35.39 19.19 35.49 17.30L35.49 17.30Q35.53 16.77 35.53 15.90Q35.53 15.02 35.49 14.50L35.49 14.50Q35.39 12.64 34.67 11.68Q33.95 10.72 32.38 10.72L32.38 10.72Q30.87 10.72 30.12 11.68Q29.37 12.64 29.30 14.50L29.30 14.50Q29.26 15.02 29.26 15.90Q29.26 16.77 29.30 17.30L29.30 17.30Q29.37 19.19 30.12 20.13Q30.87 21.08 32.38 21.08ZM50.89 25.35L50.89 25.35Q49.21 25.35 47.86 24.81Q46.52 24.27 45.55 23.20Q44.59 22.13 44.07 20.61Q43.54 19.09 43.47 17.13L43.47 17.13Q43.44 16.42 43.44 15.88Q43.44 15.34 43.47 14.64L43.47 14.64Q43.54 12.78 44.07 11.26Q44.59 9.74 45.54 8.67Q46.48 7.60 47.85 7.03Q49.21 6.45 50.89 6.45L50.89 6.45Q52.64 6.45 53.90 7.03Q55.16 7.60 56.04 8.51L56.04 8.51L56.04 1.02Q56.04 0.64 56.28 0.39Q56.53 0.15 56.91 0.15L56.91 0.15L61.18 0.15Q61.53 0.15 61.79 0.39Q62.06 0.64 62.06 1.02L62.06 1.02L62.06 24.13Q62.06 24.48 61.79 24.74Q61.53 25 61.18 25L61.18 25L57.23 25Q56.84 25 56.60 24.74Q56.35 24.48 56.35 24.13L56.35 24.13L56.35 23.00Q55.51 24.02 54.18 24.68Q52.85 25.35 50.89 25.35ZM52.82 20.66L52.82 20.66Q53.97 20.66 54.65 20.15Q55.34 19.64 55.67 18.84Q56.00 18.04 56.04 17.09L56.04 17.09Q56.07 16.39 56.07 15.76Q56.07 15.13 56.04 14.46L56.04 14.46Q56.00 13.59 55.65 12.84Q55.30 12.08 54.60 11.61Q53.90 11.14 52.82 11.14L52.82 11.14Q51.66 11.14 50.98 11.63Q50.30 12.12 50.00 12.96Q49.70 13.80 49.63 14.81L49.63 14.81Q49.53 15.90 49.63 16.98L49.63 16.98Q49.70 18 50.00 18.84Q50.30 19.68 50.98 20.17Q51.66 20.66 52.82 20.66ZM73.54 25.35L73.54 25.35Q69.41 25.35 66.96 23.11Q64.51 20.87 64.40 16.46L64.40 16.46Q64.40 16.21 64.40 15.83Q64.40 15.44 64.40 15.23L64.40 15.23Q64.51 12.47 65.64 10.49Q66.78 8.51 68.79 7.48Q70.81 6.45 73.50 6.45L73.50 6.45Q76.58 6.45 78.59 7.67Q80.61 8.90 81.62 11.00Q82.64 13.10 82.64 15.79L82.64 15.79L82.64 16.63Q82.64 17.02 82.39 17.27Q82.15 17.51 81.76 17.51L81.76 17.51L70.56 17.51Q70.56 17.54 70.56 17.61Q70.56 17.68 70.56 17.75L70.56 17.75Q70.60 18.77 70.93 19.61Q71.26 20.45 71.91 20.94Q72.56 21.43 73.50 21.43L73.50 21.43Q74.20 21.43 74.67 21.20Q75.15 20.98 75.46 20.68Q75.78 20.38 75.95 20.17L75.95 20.17Q76.27 19.79 76.46 19.70Q76.65 19.61 77.07 19.61L77.07 19.61L81.41 19.61Q81.76 19.61 81.99 19.82Q82.22 20.03 82.18 20.38L82.18 20.38Q82.15 20.98 81.59 21.81Q81.03 22.66 79.96 23.48Q78.89 24.30 77.28 24.82Q75.67 25.35 73.54 25.35ZM70.56 13.97L70.56 14.04L76.48 14.04L76.48 13.97Q76.48 12.82 76.14 12.00Q75.81 11.17 75.13 10.72Q74.45 10.26 73.50 10.26L73.50 10.26Q72.59 10.26 71.93 10.72Q71.26 11.17 70.91 12.00Q70.56 12.82 70.56 13.97L70.56 13.97ZM89.88 25L85.75 25Q85.37 25 85.12 24.74Q84.88 24.48 84.88 24.13L84.88 24.13L84.88 1.02Q84.88 0.64 85.12 0.39Q85.37 0.15 85.75 0.15L85.75 0.15L89.88 0.15Q90.27 0.15 90.51 0.39Q90.76 0.64 90.76 1.02L90.76 1.02L90.76 24.13Q90.76 24.48 90.51 24.74Q90.27 25 89.88 25L89.88 25ZM99.30 25.35L99.30 25.35Q97.41 25.35 95.92 24.63Q94.43 23.91 93.56 22.69Q92.68 21.46 92.68 19.93L92.68 19.93Q92.68 17.44 94.71 15.99Q96.74 14.53 100.10 14.01L100.10 14.01L104.48 13.34L104.48 12.85Q104.48 11.59 103.95 10.93Q103.43 10.26 102.03 10.26L102.03 10.26Q101.05 10.26 100.43 10.65Q99.82 11.03 99.47 11.70L99.47 11.70Q99.16 12.15 98.60 12.15L98.60 12.15L94.68 12.15Q94.29 12.15 94.08 11.93Q93.87 11.70 93.91 11.38L93.91 11.38Q93.91 10.75 94.38 9.93Q94.85 9.11 95.83 8.30Q96.81 7.50 98.35 6.97Q99.89 6.45 102.10 6.45L102.10 6.45Q104.34 6.45 105.95 6.97Q107.56 7.50 108.57 8.44Q109.59 9.39 110.06 10.67Q110.53 11.94 110.53 13.48L110.53 13.48L110.53 24.13Q110.53 24.48 110.27 24.74Q110.01 25 109.66 25L109.66 25L105.60 25Q105.21 25 104.97 24.74Q104.72 24.48 104.72 24.13L104.72 24.13L104.72 22.90Q104.27 23.57 103.50 24.13Q102.73 24.68 101.69 25.02Q100.66 25.35 99.30 25.35ZM100.94 21.36L100.94 21.36Q101.96 21.36 102.78 20.92Q103.60 20.48 104.07 19.56Q104.55 18.63 104.55 17.23L104.55 17.23L104.55 16.74L101.57 17.27Q99.93 17.54 99.17 18.12Q98.42 18.70 98.42 19.47L98.42 19.47Q98.42 20.06 98.77 20.48Q99.12 20.91 99.70 21.13Q100.28 21.36 100.94 21.36Z"/></g><path d="M116 1.9V8.5M112.7 5.2H119.3" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round"/></svg></a>';
+export function badgeHtml(config) {
+    return config.showBadge ? BADGE_HTML : "";
+}

package/dist/admin-token.d.ts

@@ -0,0 +1,6 @@
+/** So sánh không lộ thời gian: so hai HMAC có độ dài cố định thay vì so chuỗi gốc. */
+export declare function safeEqual(secret: string, a: string, b: string): Promise<boolean>;
+/** Dấu vân tay của mật khẩu: đổi mật khẩu thì mọi phiên cũ mất hiệu lực. */
+export declare function passwordFingerprint(secret: string, password: string): Promise<string>;
+export declare function signAdminToken(secret: string, fingerprint: string, expiresAtMs: number): Promise<string>;
+export declare function verifyAdminToken(secret: string, fingerprint: string, token: string | undefined, nowMs: number): Promise<boolean>;

package/dist/admin-token.js

@@ -0,0 +1,34 @@
+// Mã phiên cho khu vực quản lý của chủ website. Thuần (không đọc env/cookie) nên kiểm thử được.
+// Hodela quản lý file này: không sửa.
+const encoder = new TextEncoder();
+async function hmacHex(secret, message) {
+    const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(message)));
+    return Array.from(sig, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** So sánh không lộ thời gian: so hai HMAC có độ dài cố định thay vì so chuỗi gốc. */
+export async function safeEqual(secret, a, b) {
+    const [ha, hb] = await Promise.all([hmacHex(secret, `cmp:${a}`), hmacHex(secret, `cmp:${b}`)]);
+    let diff = 0;
+    for (let i = 0; i < ha.length; i++)
+        diff |= ha.charCodeAt(i) ^ hb.charCodeAt(i);
+    return diff === 0;
+}
+/** Dấu vân tay của mật khẩu: đổi mật khẩu thì mọi phiên cũ mất hiệu lực. */
+export async function passwordFingerprint(secret, password) {
+    return (await hmacHex(secret, `pw:${password}`)).slice(0, 32);
+}
+export async function signAdminToken(secret, fingerprint, expiresAtMs) {
+    return `${expiresAtMs}.${await hmacHex(secret, `admin:${expiresAtMs}:${fingerprint}`)}`;
+}
+export async function verifyAdminToken(secret, fingerprint, token, nowMs) {
+    if (!token)
+        return false;
+    const dot = token.indexOf(".");
+    if (dot < 1)
+        return false;
+    const exp = Number(token.slice(0, dot));
+    if (!Number.isFinite(exp) || exp <= nowMs)
+        return false;
+    return safeEqual(secret, token, await signAdminToken(secret, fingerprint, exp));
+}

package/dist/analytics.d.ts

@@ -0,0 +1,9 @@
+export type AnalyticsConfig = {
+    googleAnalytics?: string;
+    plausible?: string;
+    metaPixel?: string;
+};
+/** Đọc cấu hình từ binding HODELA_ANALYTICS (JSON). Giá trị sai định dạng bị bỏ, không bao giờ ném lỗi. */
+export declare function parseAnalyticsConfig(raw: unknown): AnalyticsConfig;
+/** HTML chèn vào cuối <head>. Rỗng nếu chưa bật dịch vụ nào. Mọi ID đã qua kiểm tra định dạng. */
+export declare function analyticsHeadSnippet(config: AnalyticsConfig): string;

package/dist/analytics.js

@@ -0,0 +1,50 @@
+// Mã đo lường do chủ web bật trong Cài đặt → Analytics. Hodela chèn vào <head> của mọi trang HTML
+// khi website đã xuất bản (không chèn ở bản xem trước). Không tự thêm Google Analytics,
+// Plausible hay Meta Pixel vào code của website: sẽ bị đếm hai lần.
+//
+// File này do Hodela quản lý (cùng src/server.ts), đừng sửa.
+const GA_ID = /^G-[A-Z0-9]{4,20}$/;
+const PLAUSIBLE_DOMAIN = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+const PIXEL_ID = /^\d{5,20}$/;
+/** Đọc cấu hình từ binding HODELA_ANALYTICS (JSON). Giá trị sai định dạng bị bỏ, không bao giờ ném lỗi. */
+export function parseAnalyticsConfig(raw) {
+    if (typeof raw !== "string" || raw === "")
+        return {};
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!json || typeof json !== "object")
+        return {};
+    const o = json;
+    const out = {};
+    if (typeof o["googleAnalytics"] === "string" && GA_ID.test(o["googleAnalytics"])) {
+        out.googleAnalytics = o["googleAnalytics"];
+    }
+    if (typeof o["plausible"] === "string" && PLAUSIBLE_DOMAIN.test(o["plausible"])) {
+        out.plausible = o["plausible"];
+    }
+    if (typeof o["metaPixel"] === "string" && PIXEL_ID.test(o["metaPixel"])) {
+        out.metaPixel = o["metaPixel"];
+    }
+    return out;
+}
+/** HTML chèn vào cuối <head>. Rỗng nếu chưa bật dịch vụ nào. Mọi ID đã qua kiểm tra định dạng. */
+export function analyticsHeadSnippet(config) {
+    const parts = [];
+    if (config.googleAnalytics && GA_ID.test(config.googleAnalytics)) {
+        const id = config.googleAnalytics;
+        parts.push(`<script async src="https://www.googletagmanager.com/gtag/js?id=${id}"></script>`, `<script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments)}gtag("js",new Date());gtag("config","${id}");</script>`);
+    }
+    if (config.plausible && PLAUSIBLE_DOMAIN.test(config.plausible)) {
+        parts.push(`<script defer data-domain="${config.plausible}" src="https://plausible.io/js/script.js"></script>`);
+    }
+    if (config.metaPixel && PIXEL_ID.test(config.metaPixel)) {
+        const id = config.metaPixel;
+        parts.push(`<script>!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version="2.0";n.queue=[];t=b.createElement(e);t.async=!0;t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,document,"script","https://connect.facebook.net/en_US/fbevents.js");fbq("init","${id}");fbq("track","PageView");</script>`);
+    }
+    return parts.join("");
+}

package/dist/customer-auth.d.ts

@@ -0,0 +1,8 @@
+/** Băm mật khẩu để LƯU VÀO DATABASE (cột password_hash). Không bao giờ lưu mật khẩu gốc. */
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(password: string, stored: string): Promise<boolean>;
+/** Mật khẩu hợp lệ cho khách: 8–128 ký tự. Trả thông báo lỗi tiếng Việt, hoặc null nếu ổn. */
+export declare function passwordProblem(password: string): string | null;
+/** Mã phiên `<customerId>.<hạn>.<chữ ký>`; khác miền chữ ký với phiên quản lý nên không dùng lẫn được. */
+export declare function signCustomerToken(secret: string, customerId: string, expiresAtMs: number): Promise<string>;
+export declare function verifyCustomerToken(secret: string, token: string | undefined, nowMs: number): Promise<string | null>;

package/dist/customer-auth.js

@@ -0,0 +1,58 @@
+// Tài khoản của KHÁCH HÀNG cuối (khác khu vực quản lý của chủ web): băm mật khẩu và mã phiên. Thuần, kiểm thử được.
+// Hodela quản lý file này: không sửa. Dùng qua "@/lib/customer-auth.server".
+const enc = new TextEncoder();
+// Cloudflare Workers giới hạn PBKDF2 tối đa 100.000 vòng.
+const ITERATIONS = 100_000;
+const b64 = (bytes) => btoa(String.fromCharCode(...bytes));
+const unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+async function pbkdf2(password, salt, iterations) {
+    const key = await crypto.subtle.importKey("raw", enc.encode(password), "PBKDF2", false, ["deriveBits"]);
+    return new Uint8Array(await crypto.subtle.deriveBits({ name: "PBKDF2", hash: "SHA-256", salt, iterations }, key, 256));
+}
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+/** Băm mật khẩu để LƯU VÀO DATABASE (cột password_hash). Không bao giờ lưu mật khẩu gốc. */
+export async function hashPassword(password) {
+    const salt = crypto.getRandomValues(new Uint8Array(16));
+    return `pbkdf2$${ITERATIONS}$${b64(salt)}$${b64(await pbkdf2(password, salt, ITERATIONS))}`;
+}
+export async function verifyPassword(password, stored) {
+    const [scheme, iter, salt, hash] = stored.split("$");
+    const iterations = Number(iter);
+    if (scheme !== "pbkdf2" || !salt || !hash || !Number.isInteger(iterations) || iterations < 1000 || iterations > ITERATIONS)
+        return false;
+    return equalBytes(await pbkdf2(password, unb64(salt), iterations), unb64(hash));
+}
+/** Mật khẩu hợp lệ cho khách: 8–128 ký tự. Trả thông báo lỗi tiếng Việt, hoặc null nếu ổn. */
+export function passwordProblem(password) {
+    if (password.length < 8)
+        return "Mật khẩu cần ít nhất 8 ký tự.";
+    if (password.length > 128)
+        return "Mật khẩu quá dài.";
+    return null;
+}
+async function hmacHex(secret, message) {
+    const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = new Uint8Array(await crypto.subtle.sign("HMAC", key, enc.encode(message)));
+    return Array.from(sig, (x) => x.toString(16).padStart(2, "0")).join("");
+}
+/** Mã phiên `<customerId>.<hạn>.<chữ ký>`; khác miền chữ ký với phiên quản lý nên không dùng lẫn được. */
+export async function signCustomerToken(secret, customerId, expiresAtMs) {
+    return `${customerId}.${expiresAtMs}.${await hmacHex(secret, `customer:${customerId}:${expiresAtMs}`)}`;
+}
+export async function verifyCustomerToken(secret, token, nowMs) {
+    if (!token)
+        return null;
+    const [id, exp, sig] = token.split(".");
+    const expiresAt = Number(exp);
+    if (!id || !sig || !Number.isFinite(expiresAt) || expiresAt <= nowMs)
+        return null;
+    const expected = await hmacHex(secret, `customer:${id}:${expiresAt}`);
+    return equalBytes(enc.encode(sig), enc.encode(expected)) ? id : null;
+}

package/dist/mailer.d.ts

@@ -0,0 +1,32 @@
+import { type EmailLogEntry } from "@hodela/email-js";
+export type MailProvider = "hodela" | "resend" | "none";
+export type MailInput = {
+    to: string | string[];
+    subject: string;
+    text?: string | undefined;
+    html?: string | undefined;
+    /** Người nhận bấm "Trả lời" sẽ viết cho địa chỉ này (ví dụ email khách trong form). */
+    replyTo?: string | undefined;
+    /** Gửi lại cùng khóa trong 24 giờ không tạo thêm thư (ví dụ mã đơn hàng). */
+    idempotencyKey?: string | undefined;
+};
+export type MailResult = {
+    sent: boolean;
+    provider: MailProvider;
+    reason?: "not_configured" | "rate_limited" | "failed" | "invalid" | "suppressed";
+};
+type Env = (name: string) => string | undefined;
+type Deps = {
+    env: Env;
+    mode: "preview" | "production";
+    fetch?: typeof fetch;
+};
+export declare function mailProvider(env: Env): MailProvider;
+export declare function createMailer(deps: Deps): {
+    sendMail: (input: MailInput) => Promise<MailResult>;
+    notifyOwner: (input: Omit<MailInput, "to">) => Promise<MailResult>;
+    recentMail: (limit?: number) => Promise<EmailLogEntry[]>;
+};
+/** Escape giá trị người dùng nhập trước khi đưa vào html của thư. */
+export declare function escapeMailHtml(value: string): string;
+export {};

package/dist/mailer.js

@@ -0,0 +1,82 @@
+// Gửi email thông báo (form liên hệ, đơn hàng, lịch hẹn...). Thuần (nhận env vào) nên kiểm thử được.
+// Hodela quản lý file này: không sửa. Dùng qua "@/lib/mailer.server".
+//
+// Cách gửi do chủ web chọn, suy ra từ biến môi trường (agent chỉ hỏi chủ web rồi xin đúng các biến này):
+//   • Gửi bằng Hodela     : đặt NOTIFY_EMAIL (hộp thư nhận thông báo). Hodela cấp sẵn HODELA_API_URL/HODELA_API_KEY.
+//   • Gửi bằng Resend riêng: đặt RESEND_API_KEY + MAIL_FROM (+ NOTIFY_EMAIL). Thư đi bằng tên miền của chủ web.
+//   • Không gửi email      : không đặt gì. Dữ liệu vẫn LUÔN được lưu vào database; chủ web xem ở khu vực quản lý.
+// Việc gửi thư không bao giờ ném lỗi và không bao giờ được chặn việc lưu dữ liệu.
+import { createHodelaEmailClient, HodelaEmailError } from "@hodela/email-js";
+export function mailProvider(env) {
+    if (env("RESEND_API_KEY") && env("MAIL_FROM"))
+        return "resend";
+    if (env("NOTIFY_EMAIL") && env("HODELA_API_URL") && env("HODELA_API_KEY"))
+        return "hodela";
+    return "none";
+}
+const EMAIL_RE = /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/;
+export function createMailer(deps) {
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    // Bản xem thử trong editor cũng gửi thật để chủ web thử luồng, nhưng đánh dấu rõ.
+    const subjectOf = (s) => (deps.mode === "preview" ? `[Bản thử] ${s}` : s).replace(/[\r\n]+/g, " ").slice(0, 200);
+    const hodelaClient = () => createHodelaEmailClient({ apiUrl: deps.env("HODELA_API_URL"), apiKey: deps.env("HODELA_API_KEY"), fetch: doFetch });
+    /** Thư gần đây đã gửi qua Hodela (để trang quản lý hiện trạng thái: đã gửi, trả về, bị chặn). Trả [] khi không dùng Hodela hoặc lỗi. */
+    async function recentMail(limit = 20) {
+        if (mailProvider(deps.env) !== "hodela")
+            return [];
+        try {
+            return await hodelaClient().logs(limit);
+        }
+        catch {
+            return [];
+        }
+    }
+    async function sendMail(input) {
+        const provider = mailProvider(deps.env);
+        if (provider === "none")
+            return { sent: false, provider, reason: "not_configured" };
+        const to = (Array.isArray(input.to) ? input.to : [input.to]).map((a) => a.trim()).filter(Boolean);
+        if (to.length === 0 || to.some((a) => !EMAIL_RE.test(a)) || (!input.text?.trim() && !input.html?.trim())) {
+            return { sent: false, provider, reason: "invalid" };
+        }
+        const replyTo = input.replyTo && EMAIL_RE.test(input.replyTo.trim()) ? input.replyTo.trim() : undefined;
+        try {
+            if (provider === "hodela") {
+                const sent = await hodelaClient().send({ to, subject: subjectOf(input.subject), text: input.text, html: input.html, replyTo, idempotencyKey: input.idempotencyKey });
+                // Địa chỉ từng trả thư về hoặc báo spam: nền tảng không gửi nữa.
+                if (sent.status === "suppressed")
+                    return { sent: false, provider, reason: "suppressed" };
+            }
+            else {
+                const res = await doFetch("https://api.resend.com/emails", {
+                    method: "POST",
+                    headers: { "content-type": "application/json", authorization: `Bearer ${deps.env("RESEND_API_KEY")}` },
+                    body: JSON.stringify({ from: deps.env("MAIL_FROM"), to, subject: subjectOf(input.subject), text: input.text, html: input.html, reply_to: replyTo }),
+                    signal: AbortSignal.timeout(10_000),
+                });
+                if (!res.ok) {
+                    console.warn(`[mailer] Resend trả HTTP ${res.status}`);
+                    return { sent: false, provider, reason: res.status === 429 ? "rate_limited" : "failed" };
+                }
+            }
+            return { sent: true, provider };
+        }
+        catch (e) {
+            const limited = e instanceof HodelaEmailError && e.code === "rate_limited";
+            console.warn(`[mailer] không gửi được (${provider}): ${e instanceof Error ? e.message : String(e)}`);
+            return { sent: false, provider, reason: limited ? "rate_limited" : "failed" };
+        }
+    }
+    /** Gửi tới hộp thư của chủ web (NOTIFY_EMAIL). Chưa đặt NOTIFY_EMAIL thì bỏ qua êm. */
+    async function notifyOwner(input) {
+        const to = deps.env("NOTIFY_EMAIL");
+        if (!to)
+            return { sent: false, provider: mailProvider(deps.env), reason: "not_configured" };
+        return sendMail({ ...input, to });
+    }
+    return { sendMail, notifyOwner, recentMail };
+}
+/** Escape giá trị người dùng nhập trước khi đưa vào html của thư. */
+export function escapeMailHtml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}

package/dist/seo.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Metadata SEO cho `head()` của mỗi route: title, description, Open Graph, Twitter, canonical.
+ * Dùng một lời gọi thay vì tự viết từng thẻ để mọi trang nhất quán và không sót thẻ nào.
+ *
+ *   head: () => seo({ title: "Thực đơn | Quán Mây", description: "…", path: "/thuc-don" })
+ *
+ * Mọi thuộc tính tùy chọn nhận được cả `undefined` (tsconfig bật exactOptionalPropertyTypes), nên truyền thẳng
+ * `image: item.image` với `item.image: string | undefined` là hợp lệ.
+ */
+export type SeoInput = {
+    /** Tiêu đề trang, ≤ ~60 ký tự, riêng cho từng trang. */
+    title: string;
+    /** Mô tả trang, ~70–160 ký tự, riêng cho từng trang. */
+    description: string;
+    /** Đường dẫn của route (vd. "/thuc-don"); dùng cho canonical và og:url khi biết địa chỉ website. */
+    path?: string | undefined;
+    /** Ảnh chia sẻ (đường dẫn trong website hoặc URL tuyệt đối). */
+    image?: string | undefined;
+    type?: "website" | "article" | undefined;
+    siteName?: string | undefined;
+    /** Ví dụ "vi_VN". */
+    locale?: string | undefined;
+    /** Trang không để công cụ tìm kiếm lập chỉ mục (khu vực quản lý, trang cảm ơn). */
+    noindex?: boolean | undefined;
+};
+type Meta = {
+    title?: string;
+    name?: string;
+    property?: string;
+    content?: string;
+};
+type Link = {
+    rel: string;
+    href: string;
+};
+/** URL tuyệt đối cho đường dẫn trong website, dùng khi tự viết thẻ meta thô (vd. `og:image` trong `__root.tsx`). */
+export declare function absoluteUrl(value: string): string;
+export declare function seo(input: SeoInput): {
+    meta: Meta[];
+    links: Link[];
+};
+/** Dữ liệu có cấu trúc cho doanh nghiệp địa phương: dùng trong `scripts` của head() ở trang chủ/liên hệ. */
+export declare function localBusinessJsonLd(input: {
+    name: string;
+    description?: string | undefined;
+    telephone?: string | undefined;
+    email?: string | undefined;
+    address?: {
+        street: string;
+        city: string;
+        region?: string | undefined;
+        country?: string | undefined;
+    } | undefined;
+    openingHours?: string[] | undefined;
+    image?: string | undefined;
+}): {
+    type: string;
+    children: string;
+};
+export {};

package/dist/seo.js

@@ -0,0 +1,99 @@
+/**
+ * Metadata SEO cho `head()` của mỗi route: title, description, Open Graph, Twitter, canonical.
+ * Dùng một lời gọi thay vì tự viết từng thẻ để mọi trang nhất quán và không sót thẻ nào.
+ *
+ *   head: () => seo({ title: "Thực đơn | Quán Mây", description: "…", path: "/thuc-don" })
+ *
+ * Mọi thuộc tính tùy chọn nhận được cả `undefined` (tsconfig bật exactOptionalPropertyTypes), nên truyền thẳng
+ * `image: item.image` với `item.image: string | undefined` là hợp lệ.
+ */
+import { createIsomorphicFn } from "@tanstack/react-start";
+import { getRequestUrl } from "@tanstack/react-start/server";
+/** Địa chỉ của request hiện tại: phía server lấy từ request (SSR, thứ mà trình thu thập đọc), phía client từ trình duyệt. */
+const requestOrigin = createIsomorphicFn()
+    .server(() => {
+    try {
+        return getRequestUrl().origin;
+    }
+    catch {
+        return "";
+    }
+})
+    .client(() => window.location.origin);
+/**
+ * Địa chỉ gốc công khai của website (không có "/" cuối), hoặc "" nếu chưa biết. `VITE_PUBLIC_SITE_URL` (nếu chủ web đặt) thắng;
+ * không thì dùng địa chỉ request, nên `og:image`, canonical, `og:url` luôn là URL tuyệt đối đúng tên miền đang chạy (kể cả tên miền riêng
+ * thêm sau khi build). Mạng xã hội (Facebook, Zalo) không hiển thị `og:image` là đường dẫn tương đối.
+ */
+function siteOrigin() {
+    const raw = import.meta.env?.["VITE_PUBLIC_SITE_URL"] ?? "";
+    const fromEnv = raw.trim().replace(/\/+$/, "");
+    if (fromEnv)
+        return fromEnv;
+    return requestOrigin().replace(/\/+$/, "");
+}
+function absolute(origin, value) {
+    if (/^https?:\/\//i.test(value))
+        return value;
+    return origin ? `${origin}${value.startsWith("/") ? "" : "/"}${value}` : value;
+}
+/** URL tuyệt đối cho đường dẫn trong website, dùng khi tự viết thẻ meta thô (vd. `og:image` trong `__root.tsx`). */
+export function absoluteUrl(value) {
+    return absolute(siteOrigin(), value);
+}
+export function seo(input) {
+    const origin = siteOrigin();
+    const meta = [
+        { title: input.title },
+        { name: "description", content: input.description },
+        { property: "og:title", content: input.title },
+        { property: "og:description", content: input.description },
+        { property: "og:type", content: input.type ?? "website" },
+        { name: "twitter:card", content: input.image ? "summary_large_image" : "summary" },
+        { name: "twitter:title", content: input.title },
+        { name: "twitter:description", content: input.description },
+    ];
+    if (input.noindex)
+        meta.push({ name: "robots", content: "noindex, nofollow" });
+    if (input.siteName)
+        meta.push({ property: "og:site_name", content: input.siteName });
+    if (input.locale)
+        meta.push({ property: "og:locale", content: input.locale });
+    if (input.image) {
+        const image = absolute(origin, input.image);
+        meta.push({ property: "og:image", content: image }, { name: "twitter:image", content: image });
+    }
+    const links = [];
+    if (origin && input.path) {
+        const url = `${origin}${input.path === "/" ? "" : input.path}`;
+        links.push({ rel: "canonical", href: url || origin });
+        meta.push({ property: "og:url", content: url || origin });
+    }
+    return { meta, links };
+}
+/** Dữ liệu có cấu trúc cho doanh nghiệp địa phương: dùng trong `scripts` của head() ở trang chủ/liên hệ. */
+export function localBusinessJsonLd(input) {
+    const data = {
+        "@context": "https://schema.org",
+        "@type": "LocalBusiness",
+        name: input.name,
+        ...(input.description ? { description: input.description } : {}),
+        ...(input.telephone ? { telephone: input.telephone } : {}),
+        ...(input.email ? { email: input.email } : {}),
+        ...(input.image ? { image: input.image } : {}),
+        ...(input.openingHours?.length ? { openingHours: input.openingHours } : {}),
+        ...(input.address
+            ? {
+                address: {
+                    "@type": "PostalAddress",
+                    streetAddress: input.address.street,
+                    addressLocality: input.address.city,
+                    ...(input.address.region ? { addressRegion: input.address.region } : {}),
+                    addressCountry: input.address.country ?? "VN",
+                },
+            }
+            : {}),
+    };
+    // `<` được thoát để chuỗi JSON không đóng thẻ script sớm.
+    return { type: "application/ld+json", children: JSON.stringify(data).replace(/</g, "\\u003c") };
+}

package/dist/session-cookie.d.ts

@@ -0,0 +1,15 @@
+/** `localhost`, `*.localhost`, `127.0.0.1`, `[::1]`: trình duyệt chấp nhận cookie `Secure` kể cả qua http. */
+export declare function isLocalHost(hostname: string): boolean;
+export type SessionCookieOptions = {
+    httpOnly: true;
+    path: "/";
+    maxAge: number;
+    secure: boolean;
+    sameSite: "lax" | "none";
+    partitioned?: true;
+};
+/** Thuần (dễ kiểm thử): chọn thuộc tính theo môi trường, giao thức và host của request. */
+export declare function sessionCookieOptions(env: "preview" | "production", url: {
+    protocol: string;
+    hostname: string;
+}, maxAgeSeconds: number): SessionCookieOptions;

package/dist/session-cookie.js

@@ -0,0 +1,18 @@
+// Thuộc tính cookie phiên dùng chung cho quản lý và khách. Hodela quản lý file này: không sửa.
+//
+// Preview chạy trong iframe của editor (khác site với editor nên cookie `lax` bị coi là bên thứ ba và bị chặn: đăng nhập
+// báo đúng nhưng không giữ được phiên, trong khi mở tab riêng thì được). Vì vậy preview dùng `SameSite=None; Secure;
+// Partitioned` (CHIPS: cookie gắn với trang editor chứa iframe nên không phải cookie theo dõi xuyên site). Production không
+// bị nhúng nên giữ `lax`, đây là mặc định an toàn nhất chống CSRF.
+/** `localhost`, `*.localhost`, `127.0.0.1`, `[::1]`: trình duyệt chấp nhận cookie `Secure` kể cả qua http. */
+export function isLocalHost(hostname) {
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/** Thuần (dễ kiểm thử): chọn thuộc tính theo môi trường, giao thức và host của request. */
+export function sessionCookieOptions(env, url, maxAgeSeconds) {
+    const secureContext = url.protocol === "https:" || isLocalHost(url.hostname);
+    if (env !== "production" && secureContext) {
+        return { httpOnly: true, path: "/", maxAge: maxAgeSeconds, secure: true, sameSite: "none", partitioned: true };
+    }
+    return { httpOnly: true, path: "/", maxAge: maxAgeSeconds, secure: env === "production", sameSite: "lax" };
+}

package/dist/sql-split.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Tách câu lệnh SQL cho migration. MỘT thuật toán duy nhất cho mọi nơi: kiểm tra, áp lên D1, áp lên
+ * database ngoài. File này được sao nguyên văn vào starter (`src/lib/sql-split.ts`) để website tự áp
+ * migration lúc chạy; test so khớp hai bản trên cùng một bộ mẫu. Không import gì để sao chép được.
+ */
+export type SqlDialect = "sqlite" | "postgres" | "mysql";
+export type SqlToken = {
+    kind: "word" | "ident" | "string" | "number" | "punct";
+    /** word: chữ HOA; ident: tên đã bỏ dấu nháy (giữ nguyên chữ hoa/thường); còn lại: văn bản gốc. */
+    text: string;
+    line: number;
+};
+export type SqlStatement = {
+    /** Câu lệnh đã bỏ chú thích, không có dấu `;` cuối. Đây chính là chuỗi được chạy. */
+    sql: string;
+    tokens: SqlToken[];
+    /** Dòng bắt đầu (1-based) trong file gốc, để báo lỗi. */
+    line: number;
+};
+export declare class SqlSyntaxError extends Error {
+    readonly line: number;
+    constructor(message: string, line: number);
+}
+export declare function splitSqlStatements(source: string, dialect?: SqlDialect): SqlStatement[];

package/dist/sql-split.js

@@ -0,0 +1,182 @@
+/**
+ * Tách câu lệnh SQL cho migration. MỘT thuật toán duy nhất cho mọi nơi: kiểm tra, áp lên D1, áp lên
+ * database ngoài. File này được sao nguyên văn vào starter (`src/lib/sql-split.ts`) để website tự áp
+ * migration lúc chạy; test so khớp hai bản trên cùng một bộ mẫu. Không import gì để sao chép được.
+ */
+export class SqlSyntaxError extends Error {
+    line;
+    constructor(message, line) {
+        super(message);
+        this.line = line;
+    }
+}
+const WORD_START = /[A-Za-z_\u0080-￿]/;
+const WORD_PART = /[A-Za-z0-9_$\u0080-￿]/;
+export function splitSqlStatements(source, dialect = "sqlite") {
+    const out = [];
+    let text = "";
+    let tokens = [];
+    let startLine = 0;
+    let line = 1;
+    let i = 0;
+    const n = source.length;
+    const push = (t, raw) => {
+        if (!startLine)
+            startLine = t.line;
+        tokens.push(t);
+        text += raw;
+    };
+    const flush = () => {
+        const sql = text.trim();
+        if (sql)
+            out.push({ sql, tokens, line: startLine || line });
+        text = "";
+        tokens = [];
+        startLine = 0;
+    };
+    const sep = () => {
+        if (text && !text.endsWith(" "))
+            text += " ";
+    };
+    while (i < n) {
+        const c = source[i];
+        const next = source[i + 1];
+        if (c === "\n") {
+            line += 1;
+            sep();
+            i += 1;
+            continue;
+        }
+        if (c === " " || c === "\t" || c === "\r") {
+            sep();
+            i += 1;
+            continue;
+        }
+        if (c === "-" && next === "-") {
+            while (i < n && source[i] !== "\n")
+                i += 1;
+            sep();
+            continue;
+        }
+        if (c === "/" && next === "*") {
+            const startedAt = line;
+            i += 2;
+            while (i < n && !(source[i] === "*" && source[i + 1] === "/")) {
+                if (source[i] === "\n")
+                    line += 1;
+                i += 1;
+            }
+            if (i >= n)
+                throw new SqlSyntaxError("Chú thích /* không được đóng", startedAt);
+            i += 2;
+            sep();
+            continue;
+        }
+        if (c === ";") {
+            flush();
+            i += 1;
+            continue;
+        }
+        // Chuỗi '...' (và E'...' của PostgreSQL; MySQL cho phép \ thoát ký tự).
+        if (c === "'") {
+            const startedAt = line;
+            const prev = source[i - 1];
+            const backslash = dialect === "mysql" || (dialect === "postgres" && (prev === "E" || prev === "e"));
+            let j = i + 1;
+            let closed = false;
+            while (j < n) {
+                const d = source[j];
+                if (d === "\n")
+                    line += 1;
+                if (backslash && d === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (d === "'") {
+                    if (source[j + 1] === "'") {
+                        j += 2;
+                        continue;
+                    }
+                    closed = true;
+                    break;
+                }
+                j += 1;
+            }
+            if (!closed)
+                throw new SqlSyntaxError("Chuỗi ' không được đóng", startedAt);
+            const raw = source.slice(i, j + 1);
+            push({ kind: "string", text: raw, line: startedAt }, raw);
+            i = j + 1;
+            continue;
+        }
+        // Tên có nháy: "..." (chuẩn), `...` (MySQL).
+        if (c === '"' || c === "`") {
+            const startedAt = line;
+            let j = i + 1;
+            let name = "";
+            let closed = false;
+            while (j < n) {
+                const d = source[j];
+                if (d === "\n")
+                    line += 1;
+                if (d === c) {
+                    if (source[j + 1] === c) {
+                        name += c;
+                        j += 2;
+                        continue;
+                    }
+                    closed = true;
+                    break;
+                }
+                name += d;
+                j += 1;
+            }
+            if (!closed)
+                throw new SqlSyntaxError(`Tên ${c}...${c} không được đóng`, startedAt);
+            const raw = source.slice(i, j + 1);
+            push({ kind: "ident", text: name, line: startedAt }, raw);
+            i = j + 1;
+            continue;
+        }
+        // Chuỗi dollar-quote của PostgreSQL: $$...$$ hoặc $tag$...$tag$.
+        if (c === "$" && dialect === "postgres") {
+            const m = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(source.slice(i, i + 80));
+            if (m) {
+                const startedAt = line;
+                const tag = m[0];
+                const end = source.indexOf(tag, i + tag.length);
+                if (end < 0)
+                    throw new SqlSyntaxError(`Chuỗi ${tag} không được đóng`, startedAt);
+                const raw = source.slice(i, end + tag.length);
+                for (const ch of raw)
+                    if (ch === "\n")
+                        line += 1;
+                push({ kind: "string", text: raw, line: startedAt }, raw);
+                i = end + tag.length;
+                continue;
+            }
+        }
+        if (WORD_START.test(c)) {
+            let j = i + 1;
+            while (j < n && WORD_PART.test(source[j]))
+                j += 1;
+            const raw = source.slice(i, j);
+            push({ kind: "word", text: raw.toUpperCase(), line }, raw);
+            i = j;
+            continue;
+        }
+        if (/[0-9]/.test(c)) {
+            let j = i + 1;
+            while (j < n && /[0-9A-Za-z_.]/.test(source[j]))
+                j += 1;
+            const raw = source.slice(i, j);
+            push({ kind: "number", text: raw, line }, raw);
+            i = j;
+            continue;
+        }
+        push({ kind: "punct", text: c, line }, c);
+        i += 1;
+    }
+    flush();
+    return out;
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@hodela/site",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    "./access": {
+      "types": "./dist/access.d.ts",
+      "import": "./dist/access.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics.d.ts",
+      "import": "./dist/analytics.js"
+    },
+    "./sql-split": {
+      "types": "./dist/sql-split.d.ts",
+      "import": "./dist/sql-split.js"
+    },
+    "./admin-token": {
+      "types": "./dist/admin-token.d.ts",
+      "import": "./dist/admin-token.js"
+    },
+    "./session-cookie": {
+      "types": "./dist/session-cookie.d.ts",
+      "import": "./dist/session-cookie.js"
+    },
+    "./customer-auth": {
+      "types": "./dist/customer-auth.d.ts",
+      "import": "./dist/customer-auth.js"
+    },
+    "./mailer": {
+      "types": "./dist/mailer.d.ts",
+      "import": "./dist/mailer.js"
+    },
+    "./seo": {
+      "types": "./dist/seo.d.ts",
+      "import": "./dist/seo.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@tanstack/react-start": ">=1.100.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-start": "1.169.4",
+    "@types/node": "^22.16.5",
+    "typescript": "^5.8.3",
+    "vite": "^8.3.5",
+    "vitest": "^2.1.8"
+  },
+  "description": "Mã chạy chung của website Hodela (truy cập, analytics, phiên quản trị, tài khoản khách, email, SEO, tách SQL). Starter dùng gói này thay vì chép mã vào từng website.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hodela/email-js": "0.1.1"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.