@lobehub/edge-contract 0.1.0 → 0.2.0

package/README.md

@@ -1,16 +1,20 @@
 # @lobehub/edge-contract
 
 Edge logic that more than one LobeHub repository has to agree on, kept in exactly one place.
+The gateway, landing, lobehub-cloud and lobe-chat import it instead of carrying copies.
 
-- `fixtures/*.json` — golden cases (`{ cases: [{ name, input, expected }] }`) generated from the
-  authority implementation of each piece of logic. Every repository that still carries its own
-  copy runs that copy against these cases until it switches to importing from here.
-- `src/*` — the shared implementations, one subpath export each.
+| Subpath | What it owns |
+| --- | --- |
+| `./landing-locales` | The URL path prefixes landing serves, and the default (`en`, at the bare path). |
+| `./seo-topics` | The discover topics landing server-renders for `?q=`. |
+| `./request-locale` | The app locale list and how a request picks one (`hl`, then the `LOBE_LOCALE` cookie, then Accept-Language). |
+| `./last-workspace-cookie` | The `LOBE_LAST_WORKSPACE` cookie format. |
+| `./acquisition-context` | The signed `lh_acq` first-touch cookie, landing click ids and the attribution params lifted onto `/signin`. |
 
-Design: `lobehub-gateway/docs/ryugi/specs/2026-11-06-logic-dedupe-design.md`.
+`fixtures/*.json` are golden cases (`{ cases: [{ name, input, expected }] }`) captured from the
+implementations this package replaced. They are frozen: a change that fails one is a behavior
+change every consumer will see, so update the case on purpose, in the same commit.
 
-Regenerate fixtures from the authority repositories (checked out as siblings of this one):
+Design: `lobehub-gateway/docs/ryugi/specs/2026-11-06-logic-dedupe-design.md`.
 
-```bash
-pnpm generate:fixtures
-```
+Releases: bump `version`, push a `v<version>` tag; CI publishes to npm.

package/dist/acquisition-context.d.ts

@@ -0,0 +1,12 @@
+export declare const ACQUISITION_CONTEXT_COOKIE = "lh_acq";
+export declare const ACQUISITION_CONTEXT_MAX_AGE_SECONDS: number;
+export interface AcquisitionContext {
+    capturedAt: string;
+    lhCid: string;
+}
+export declare const parseLandingClickId: (value: unknown) => string | undefined;
+export declare const captureAcquisitionContext: (request: Pick<Request, "url">, now?: Date) => AcquisitionContext | null;
+export declare const signAcquisitionContext: (context: AcquisitionContext, secret: string) => Promise<string>;
+export declare const verifyAcquisitionContext: (token: string, secret: string, now?: Date) => Promise<AcquisitionContext | null>;
+export declare const readAcquisitionContextCookie: (cookieHeader: string | null) => string | null;
+export declare const ATTRIBUTION_PARAMS: ReadonlySet<string>;

package/dist/acquisition-context.js

@@ -0,0 +1,175 @@
+export const ACQUISITION_CONTEXT_COOKIE = 'lh_acq';
+export const ACQUISITION_CONTEXT_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+const ACQUISITION_CONTEXT_VERSION = 1;
+const MAX_COOKIE_LENGTH = 1024;
+const MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
+const SIGNING_SCOPE = 'lh-acquisition-context.v1:';
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+const AUTH_PATHS = new Set(['/signin', '/signup']);
+// Landing issues lh_cid with crypto.randomUUID(). Treat it only as an opaque correlation ID.
+const LH_CID_PATTERN = /^[\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}$/i;
+export const parseLandingClickId = (value) => {
+    if (typeof value !== 'string' || !LH_CID_PATTERN.test(value))
+        return;
+    return value.toLowerCase();
+};
+const sanitizeCapturedAt = (value) => {
+    if (typeof value !== 'string')
+        return;
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        return;
+    return new Date(timestamp).toISOString();
+};
+const sanitizeContext = (value) => {
+    if (!value || typeof value !== 'object')
+        return null;
+    const candidate = value;
+    if (candidate.version !== ACQUISITION_CONTEXT_VERSION)
+        return null;
+    const capturedAt = sanitizeCapturedAt(candidate.capturedAt);
+    const lhCid = parseLandingClickId(candidate.lhCid);
+    if (!capturedAt || !lhCid)
+        return null;
+    return { capturedAt, lhCid };
+};
+const serializeContext = (context) => ({
+    capturedAt: context.capturedAt,
+    lhCid: context.lhCid,
+    version: ACQUISITION_CONTEXT_VERSION,
+});
+const encodeBase64Url = (value) => {
+    let binary = '';
+    for (const byte of value)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+};
+const decodeBase64Url = (value) => {
+    if (!/^[\w-]+$/.test(value))
+        throw new Error('Invalid base64url value');
+    const base64 = value.replaceAll('-', '+').replaceAll('_', '/');
+    const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+    const binary = atob(padded);
+    const decoded = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        decoded[index] = binary.charCodeAt(index);
+    }
+    return decoded;
+};
+const importSigningKey = (secret, usages) => crypto.subtle.importKey('raw', textEncoder.encode(secret), { hash: 'SHA-256', name: 'HMAC' }, false, usages);
+const getSigningInput = (payload) => textEncoder.encode(`${SIGNING_SCOPE}${payload}`).buffer;
+const getCaptureUrl = (requestUrl) => {
+    if (!AUTH_PATHS.has(requestUrl.pathname))
+        return requestUrl;
+    const callbackUrl = requestUrl.searchParams.get('callbackUrl');
+    if (!callbackUrl)
+        return requestUrl;
+    try {
+        const parsed = new URL(callbackUrl, requestUrl.origin);
+        return parsed.origin === requestUrl.origin ? parsed : requestUrl;
+    }
+    catch {
+        return requestUrl;
+    }
+};
+export const captureAcquisitionContext = (request, now = new Date()) => {
+    const requestUrl = new URL(request.url);
+    const captureUrl = getCaptureUrl(requestUrl);
+    const lhCid = parseLandingClickId(captureUrl.searchParams.get('lh_cid')) ??
+        parseLandingClickId(requestUrl.searchParams.get('lh_cid'));
+    if (!lhCid)
+        return null;
+    return {
+        capturedAt: now.toISOString(),
+        lhCid,
+    };
+};
+export const signAcquisitionContext = async (context, secret) => {
+    if (!secret)
+        throw new Error('Acquisition context signing secret is required');
+    const sanitized = sanitizeContext({
+        ...context,
+        version: ACQUISITION_CONTEXT_VERSION,
+    });
+    if (!sanitized)
+        throw new Error('Invalid acquisition context');
+    const payload = encodeBase64Url(textEncoder.encode(JSON.stringify(serializeContext(sanitized))));
+    const key = await importSigningKey(secret, ['sign']);
+    const signature = new Uint8Array(await crypto.subtle.sign('HMAC', key, getSigningInput(payload)));
+    const token = `${payload}.${encodeBase64Url(signature)}`;
+    if (token.length > MAX_COOKIE_LENGTH)
+        throw new Error('Acquisition context cookie is too large');
+    return token;
+};
+export const verifyAcquisitionContext = async (token, secret, now = new Date()) => {
+    if (!token || !secret || token.length > MAX_COOKIE_LENGTH)
+        return null;
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 2)
+            return null;
+        const [payload, encodedSignature] = parts;
+        const key = await importSigningKey(secret, ['verify']);
+        const valid = await crypto.subtle.verify('HMAC', key, decodeBase64Url(encodedSignature), getSigningInput(payload));
+        if (!valid)
+            return null;
+        const context = sanitizeContext(JSON.parse(textDecoder.decode(decodeBase64Url(payload))));
+        if (!context)
+            return null;
+        const capturedAt = Date.parse(context.capturedAt);
+        const nowTimestamp = now.getTime();
+        if (capturedAt > nowTimestamp + MAX_FUTURE_SKEW_MS ||
+            nowTimestamp - capturedAt > ACQUISITION_CONTEXT_MAX_AGE_SECONDS * 1000) {
+            return null;
+        }
+        return context;
+    }
+    catch {
+        return null;
+    }
+};
+export const readAcquisitionContextCookie = (cookieHeader) => {
+    if (!cookieHeader)
+        return null;
+    for (const part of cookieHeader.split(';')) {
+        const separator = part.indexOf('=');
+        if (separator < 0)
+            continue;
+        const name = part.slice(0, separator).trim();
+        if (name !== ACQUISITION_CONTEXT_COOKIE)
+            continue;
+        const value = part.slice(separator + 1).trim();
+        try {
+            return decodeURIComponent(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+};
+// Non-utm_* attribution params posthog-js auto-captures (its CAMPAIGN_PARAMS minus the five
+// utm_* keys). Whoever redirects a visitor to /signin lifts these, plus every utm_*, onto the
+// top-level URL so PostHog's $pageview there records them.
+export const ATTRIBUTION_PARAMS = new Set([
+    'gad_source',
+    'mc_cid',
+    'gclid',
+    'gclsrc',
+    'dclid',
+    'gbraid',
+    'wbraid',
+    'fbclid',
+    'msclkid',
+    'twclid',
+    'li_fat_id',
+    'igshid',
+    'ttclid',
+    'rdt_cid',
+    'epik',
+    'qclid',
+    'sccid',
+    'irclid',
+    '_kx',
+]);

package/dist/last-workspace-cookie.d.ts

@@ -0,0 +1,7 @@
+export declare const LAST_WORKSPACE_COOKIE = "LOBE_LAST_WORKSPACE";
+export declare const LAST_WORKSPACE_COOKIE_MAX_AGE: number;
+export declare const LAST_WORKSPACE_SLUG_PATTERN: RegExp;
+export declare const LAST_WORKSPACE_SLUG_MIN = 3;
+export declare const LAST_WORKSPACE_SLUG_MAX = 32;
+export declare const formatLastWorkspaceCookie: (userId: string, slug: string) => string | null;
+export declare const parseLastWorkspaceCookie: (raw: string | undefined | null, userId: string | undefined | null) => string | null;

package/dist/last-workspace-cookie.js

@@ -0,0 +1,30 @@
+// Not httpOnly: the client rewrites it on every explicit workspace switch. It carries no
+// authority (workspace scope is the `X-Workspace-Id` header, checked against membership), so
+// a forged value only sends its own browser to a URL that 404s.
+export const LAST_WORKSPACE_COOKIE = 'LOBE_LAST_WORKSPACE';
+export const LAST_WORKSPACE_COOKIE_MAX_AGE = 60 * 60 * 24 * 90;
+// The same shape as lobehub-cloud's WORKSPACE_SLUG_PATTERN / _MIN / _MAX, kept here rather than
+// imported because that module also carries the reserved-slug tables, which no edge bundle
+// should pay for. Anything failing it is ignored rather than sanitized, so a tampered cookie
+// cannot smuggle `../`, a protocol or CRLF into a Location header.
+export const LAST_WORKSPACE_SLUG_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+export const LAST_WORKSPACE_SLUG_MIN = 3;
+export const LAST_WORKSPACE_SLUG_MAX = 32;
+const isValidSlug = (slug) => slug.length >= LAST_WORKSPACE_SLUG_MIN &&
+    slug.length <= LAST_WORKSPACE_SLUG_MAX &&
+    LAST_WORKSPACE_SLUG_PATTERN.test(slug);
+export const formatLastWorkspaceCookie = (userId, slug) => isValidSlug(slug) ? `${userId}:${slug}` : null;
+// Format and ownership only: whether the slug still names a workspace the user belongs to
+// needs the workspace list, so staleness is healed on the client.
+export const parseLastWorkspaceCookie = (raw, userId) => {
+    if (!raw || !userId)
+        return null;
+    // A userId never contains `:`, so the first one is the separator.
+    const separator = raw.indexOf(':');
+    if (separator <= 0)
+        return null;
+    if (raw.slice(0, separator) !== userId)
+        return null;
+    const slug = raw.slice(separator + 1);
+    return isValidSlug(slug) ? slug : null;
+};

package/dist/request-locale.d.ts

@@ -0,0 +1,13 @@
+export declare const appLocales: readonly ["ar", "bg-BG", "de-DE", "en-US", "es-ES", "fr-FR", "ja-JP", "ko-KR", "pt-BR", "ru-RU", "tr-TR", "zh-CN", "zh-TW", "vi-VN", "fa-IR", "it-IT", "pl-PL", "nl-NL"];
+export type AppLocale = (typeof appLocales)[number];
+export declare const DEFAULT_APP_LOCALE = "en-US";
+export declare const LOCALE_QUERY_PARAM = "hl";
+export declare const LOCALE_COOKIE = "LOBE_LOCALE";
+export interface LocaleVocabulary<T extends string> {
+    fallback: T;
+    tags: readonly T[];
+}
+export declare function matchLocaleTag(tag: string | undefined): AppLocale | undefined;
+export declare function matchLocaleTag<T extends string>(tag: string | undefined, tags: readonly T[]): T | undefined;
+export declare function resolveRequestLocale(request: Request): AppLocale;
+export declare function resolveRequestLocale<T extends string>(request: Request, vocabulary: LocaleVocabulary<T>): T;

package/dist/request-locale.js

@@ -0,0 +1,97 @@
+export const appLocales = [
+    'ar',
+    'bg-BG',
+    'de-DE',
+    'en-US',
+    'es-ES',
+    'fr-FR',
+    'ja-JP',
+    'ko-KR',
+    'pt-BR',
+    'ru-RU',
+    'tr-TR',
+    'zh-CN',
+    'zh-TW',
+    'vi-VN',
+    'fa-IR',
+    'it-IT',
+    'pl-PL',
+    'nl-NL',
+];
+export const DEFAULT_APP_LOCALE = 'en-US';
+export const LOCALE_QUERY_PARAM = 'hl';
+export const LOCALE_COOKIE = 'LOBE_LOCALE';
+const AUTO_LOCALE = 'auto';
+const APP_VOCABULARY = { fallback: DEFAULT_APP_LOCALE, tags: appLocales };
+const decodeCookieValue = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+const readCookie = (header, name) => {
+    if (!header)
+        return undefined;
+    for (const part of header.split(';')) {
+        const separator = part.indexOf('=');
+        if (separator === -1 || part.slice(0, separator).trim() !== name)
+            continue;
+        return decodeCookieValue(part.slice(separator + 1).trim());
+    }
+    return undefined;
+};
+// Accept-Language is case-insensitive but the vocabulary is canonical BCP 47: without this,
+// `zh-cn` misses `zh-CN` and silently degrades to the fallback.
+const canonicalizeTag = (tag) => {
+    const [language = '', ...rest] = tag.split('-');
+    return [
+        language.toLowerCase(),
+        ...rest.map((part) => (part.length === 2 ? part.toUpperCase() : part)),
+    ].join('-');
+};
+// Aliases resolve to a prefix rather than a fixed tag, so a vocabulary without the aliased
+// language simply finds nothing.
+const aliasPrefix = (lowerTag) => {
+    if (lowerTag.startsWith('ar'))
+        return 'ar';
+    if (lowerTag.startsWith('fa'))
+        return 'fa';
+    if (lowerTag.startsWith('cn'))
+        return 'zh-CN';
+    if (lowerTag.startsWith('zh-hans'))
+        return 'zh-CN';
+    if (lowerTag.startsWith('zh-hant'))
+        return 'zh-TW';
+    return undefined;
+};
+export function matchLocaleTag(tag, tags = appLocales) {
+    if (!tag)
+        return undefined;
+    const candidate = aliasPrefix(tag.toLowerCase()) ?? canonicalizeTag(tag);
+    return tags.find((supported) => supported.startsWith(candidate));
+}
+const parseAcceptLanguage = (header) => (header ?? '')
+    .split(',')
+    .map((part) => {
+    const [tag = '', ...params] = part.trim().split(';');
+    const quality = params.map((param) => param.trim()).find((param) => param.startsWith('q='));
+    const weight = quality ? Number(quality.slice(2)) : 1;
+    return { tag: tag.trim(), weight: Number.isFinite(weight) ? weight : 0 };
+})
+    .filter((candidate) => candidate.tag.length > 0 && candidate.tag !== '*')
+    .sort((a, b) => b.weight - a.weight)
+    .map((candidate) => candidate.tag);
+export function resolveRequestLocale(request, { fallback, tags } = APP_VOCABULARY) {
+    const explicit = new URL(request.url).searchParams.get(LOCALE_QUERY_PARAM) ||
+        readCookie(request.headers.get('cookie'), LOCALE_COOKIE);
+    if (explicit && explicit !== AUTO_LOCALE)
+        return matchLocaleTag(explicit, tags) ?? fallback;
+    for (const tag of parseAcceptLanguage(request.headers.get('accept-language'))) {
+        const matched = matchLocaleTag(tag, tags);
+        if (matched)
+            return matched;
+    }
+    return fallback;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobehub/edge-contract",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One implementation of the edge logic shared by the LobeHub gateway, landing, cloud and lobe-chat, plus golden fixtures every copy is tested against.",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,18 @@
       "types": "./dist/seo-topics.d.ts",
       "default": "./dist/seo-topics.js"
     },
+    "./request-locale": {
+      "types": "./dist/request-locale.d.ts",
+      "default": "./dist/request-locale.js"
+    },
+    "./last-workspace-cookie": {
+      "types": "./dist/last-workspace-cookie.d.ts",
+      "default": "./dist/last-workspace-cookie.js"
+    },
+    "./acquisition-context": {
+      "types": "./dist/acquisition-context.d.ts",
+      "default": "./dist/acquisition-context.js"
+    },
     "./fixtures/*": "./fixtures/*"
   },
   "files": [
@@ -35,7 +47,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "generate:fixtures": "bun scripts/generate-fixtures.ts"
+    "typecheck": "tsc --noEmit"
   }
 }