payment-kit 1.29.0 → 1.29.2

package/api/src/middlewares/hono/csrf.ts

@@ -0,0 +1,72 @@
+// Phase 1 (express→hono) — hono fork of @blocklet/sdk/lib/middlewares/csrf.js.
+//
+// The crypto core (sign / verify / getCsrfSecret) is framework-agnostic and is
+// REUSED VERBATIM from the SDK — tokens are byte-identical and interchangeable
+// across the express and hono engines (proven in spikes/csrf-parity.mjs, §3.2).
+// Only the express plumbing (req.cookies / res.cookie / res.status().send) is
+// replaced with hono/cookie helpers + c.text(403). The shouldGenerateToken
+// (GET) / shouldVerifyToken (mutating + cookie present + non-/mcp + non-didwallet)
+// semantics are preserved faithfully.
+import type { MiddlewareHandler } from 'hono';
+import { getCookie, setCookie } from 'hono/cookie';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { sign, verify, getCsrfSecret } from '@blocklet/sdk/lib/util/csrf';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { isDidWalletConnect } from '@blocklet/sdk/lib/util/wallet';
+
+const isEmpty = (v: unknown): boolean => v === undefined || v === null || v === '';
+
+// Express SDK: shouldGenerateToken === GET; shouldVerifyToken === mutating
+// method AND an x-csrf-token cookie already exists AND path is not /mcp AND the
+// caller is not a DID Wallet connect request.
+const MUTATING = ['POST', 'PUT', 'PATCH', 'DELETE'];
+
+/**
+ * hono csrf middleware. Faithful to the SDK express version:
+ *  - GET: if a login_token cookie exists, (re)issue x-csrf-token = sign(secret,
+ *    login_token) when it differs from the current cookie. {sameSite:'Strict',
+ *    secure:true} matches the express res.cookie attributes.
+ *  - mutating: only ENFORCED when a login_token AND an x-csrf-token cookie are
+ *    both present and the path is not /mcp and the caller is not a DID Wallet
+ *    (parity with the SDK — absent cookie => skip, never reject). The header
+ *    must equal the cookie and verify() against the login_token, else 403.
+ */
+export function csrf(): MiddlewareHandler {
+  // async (no await): the SDK crypto core is synchronous, but the handler mixes a
+  // sync Response (c.text 403) with next()'s promise — async unifies the return
+  // type to the MiddlewareHandler contract.
+  // eslint-disable-next-line require-await
+  return async (c, next) => {
+    const method = c.req.method.toUpperCase();
+    const loginToken = getCookie(c, 'login_token');
+    const existingCsrf = getCookie(c, 'x-csrf-token');
+
+    if (method === 'GET') {
+      if (loginToken) {
+        const newCsrf = sign(getCsrfSecret(), loginToken);
+        if (newCsrf !== existingCsrf) {
+          setCookie(c, 'x-csrf-token', newCsrf, { sameSite: 'Strict', secure: true });
+        }
+      }
+      return next();
+    }
+
+    if (MUTATING.includes(method)) {
+      // shouldVerifyToken parity: skip (do NOT reject) when the SDK would skip.
+      if (c.req.path.includes('/mcp')) return next();
+      if (isEmpty(loginToken)) return next();
+      if (isEmpty(existingCsrf)) return next();
+      if (isDidWalletConnect(c.req.header())) return next();
+
+      const headerCsrf = c.req.header('x-csrf-token');
+      if (existingCsrf === headerCsrf && verify(getCsrfSecret(), existingCsrf as string, loginToken as string)) {
+        return next();
+      }
+      return c.text('Invalid request: csrf token mismatch, please refresh the page try again', 403);
+    }
+
+    return next();
+  };
+}
+
+export default csrf;

package/api/src/middlewares/hono/fallback.ts

@@ -0,0 +1,194 @@
+// Phase 1 (express→hono) — hono fork of @blocklet/sdk/lib/middlewares/fallback.js.
+//
+// SPA HTML fallback: serve index.html for html GET/HEAD requests with OG meta +
+// theme styles/script + blocklet.js injection. The injection logic is ported
+// VERBATIM from the SDK (same helpers: getBlockletSettings / getBlockletJs / env,
+// @blocklet/theme buildThemeStyles+buildThemeScript, lodash escape) — only the
+// express req/res plumbing becomes hono (c.req / c.html). The express-only test
+// hook (`next(source)` in NODE_ENV=test) is dropped. did-pay calls this with no
+// getPageData, so pageData defaults to {} (title/description from env). Inert
+// until SPA serving moves off the bridge (Phase 4); forked + unit-tested now.
+import fs from 'fs';
+import { join } from 'path';
+import crypto from 'crypto';
+import type { MiddlewareHandler, Context } from 'hono';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { joinURL } from 'ufo';
+import escape from 'lodash/escape';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { RESOURCE_PATTERN } from '@blocklet/constant';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { buildThemeStyles, buildThemeScript } from '@blocklet/theme';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { env, getBlockletSettings, getBlockletJs } from '@blocklet/sdk/lib/config';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { SERVICE_PREFIX } from '@blocklet/sdk/lib/util/constants';
+import { readConfig, isTestEnv } from '../../libs/env';
+
+interface PageData {
+  title?: string;
+  description?: string;
+  ogImage?: string;
+  embed?: string;
+}
+
+interface FallbackOptions {
+  root?: string;
+  getPageData?: (c: Context) => Promise<PageData> | PageData;
+  maxLength?: number;
+  timeout?: number;
+  cacheTtl?: number;
+  injectBlockletJs?: boolean;
+}
+
+const DEFAULT_CACHE_TTL = 60 * 1000;
+const cache = new Map<
+  string,
+  { html: string; timestamp: number; etag: string; pageGroup: string; pathPrefix: string }
+>();
+const cacheEnabled = readConfig('FALLBACK_CACHE_ENABLED') === 'true' || isTestEnv();
+
+const TITLE_TAG_REGEX = /<title>(.+)<\/title>/;
+const HEAD_END_TAG = '</head>';
+
+const buildOpenGraph = (
+  pageData: Required<Pick<PageData, 'title' | 'description' | 'ogImage'>>,
+  appUrl: string
+): string =>
+  [
+    `<meta property="og:title" content="${pageData.title}" data-react-helmet="true" />`,
+    `<meta property="og:description" content="${pageData.description}" data-react-helmet="true" />`,
+    '<meta property="og:type" content="website" data-react-helmet="true" />',
+    `<meta property="og:url" content="${appUrl}" data-react-helmet="true" />`,
+    `<meta property="og:image" content="${pageData.ogImage}" data-react-helmet="true" />`,
+    '<meta name="twitter:card" content="summary_large_image" data-react-helmet="true" />',
+  ].join('\n');
+
+const validatePageData = (data: PageData, maxLength: number): void => {
+  if (data.title && data.title.length > maxLength) throw new Error('Title too long');
+  if (data.description && data.description.length > maxLength) throw new Error('Description too long');
+};
+
+const generateETag = (content: string): string => `W/"${crypto.createHash('sha1').update(content).digest('base64')}"`;
+
+const getCacheKey = (pathname: string, filePath: string, pageGroup: string, pathPrefix: string): string =>
+  crypto.createHash('sha1').update(`${pathname}:${filePath}:${pageGroup}:${pathPrefix}`).digest('base64');
+
+const tryWithTimeout = <T>(asyncFn: () => Promise<T> | T, timeout: number): Promise<T> =>
+  new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`Operation timed out after ${timeout} ms`)), timeout);
+    Promise.resolve()
+      .then(asyncFn)
+      .then((result) => resolve(result))
+      .catch((err) => reject(err))
+      .finally(() => clearTimeout(timer));
+  });
+
+function acceptsHtml(accept: string): boolean {
+  if (!accept) return true;
+  return accept.includes('text/html') || accept.includes('application/xhtml+xml') || accept.includes('*/*');
+}
+
+export function fallback(file: string, options: FallbackOptions = {}): MiddlewareHandler {
+  const filePath = options.root ? join(options.root, file) : file;
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Fallback file not found at: ${filePath}`);
+  }
+
+  return async (c, next) => {
+    const method = c.req.method.toUpperCase();
+    if (
+      (method !== 'GET' && method !== 'HEAD') ||
+      !acceptsHtml(c.req.header('accept') || '') ||
+      RESOURCE_PATTERN.test(c.req.path)
+    ) {
+      return next();
+    }
+
+    const pageGroup = c.req.header('x-page-group') || '';
+    const pathPrefix = c.req.header('x-path-prefix') || '';
+    const cacheKey = getCacheKey(c.req.path, filePath, pageGroup, pathPrefix);
+    const { theme } = getBlockletSettings();
+
+    if (cacheEnabled) {
+      const cached = cache.get(cacheKey);
+      const cacheTtl = options.cacheTtl || DEFAULT_CACHE_TTL;
+      if (
+        cached &&
+        Date.now() - cached.timestamp < cacheTtl &&
+        cached.pageGroup === pageGroup &&
+        cached.pathPrefix === pathPrefix
+      ) {
+        c.header('X-Cache', 'HIT');
+        c.header('ETag', cached.etag);
+        return c.html(cached.html);
+      }
+    }
+
+    const pageData: PageData = await tryWithTimeout(
+      options.getPageData ? () => options.getPageData!(c) : () => Promise.resolve({}),
+      options.timeout || 5000
+    );
+    validatePageData(pageData, options.maxLength || 1000);
+    const title = escape(pageData.title || (env as any).appName);
+    const description = escape(pageData.description || (env as any).appDescription);
+    const ogImage = pageData.ogImage || joinURL((env as any).appUrl || '/', SERVICE_PREFIX, '/blocklet/og.png');
+
+    let source = await fs.promises.readFile(filePath, 'utf8');
+    if (title) {
+      source = source.includes('<title>')
+        ? source.replace(TITLE_TAG_REGEX, `<title>${title}</title>`)
+        : source.replace(HEAD_END_TAG, `<title>${title}</title>${HEAD_END_TAG}`);
+    }
+    if (description && !source.includes('<meta name="description"')) {
+      source = source.replace(
+        HEAD_END_TAG,
+        `<meta name="description" content="${description}" data-react-helmet="true" />${HEAD_END_TAG}`
+      );
+    }
+    if (!source.includes('meta property="og:image"')) {
+      source = source.replace(
+        HEAD_END_TAG,
+        `${buildOpenGraph({ title, description, ogImage }, (env as any).appUrl || '/')}\n${HEAD_END_TAG}`
+      );
+    }
+    if (pageData.embed) {
+      source = source.replace(
+        HEAD_END_TAG,
+        `<link rel="blocklet-open-embed" type="application/json" href="${pageData.embed}" />${HEAD_END_TAG}`
+      );
+    }
+
+    const blockletJs = getBlockletJs(pageGroup, pathPrefix);
+    if (blockletJs && options.injectBlockletJs !== false) {
+      source = source
+        .replace('<script src="__blocklet__.js"></script>', `<script>${blockletJs}</script>`)
+        .replace('<script src="__meta__.js"></script>', `<script>${blockletJs}</script>`);
+    }
+
+    const themeStyles = buildThemeStyles(theme);
+    const themeScript = buildThemeScript(theme);
+    if (!source.includes('<style id="blocklet-theme">')) {
+      source = source.replace(HEAD_END_TAG, `${themeStyles}${HEAD_END_TAG}`);
+    }
+    if (!source.includes('<script id="blocklet-theme-script">')) {
+      source = source.replace(HEAD_END_TAG, `${themeScript}${HEAD_END_TAG}`);
+    }
+
+    const etag = generateETag(source);
+    cache.set(cacheKey, { html: source, timestamp: Date.now(), etag, pageGroup, pathPrefix });
+
+    if (options.cacheTtl) {
+      c.header('Cache-Control', `public, max-age=${options.cacheTtl}`);
+    } else {
+      c.header('Surrogate-Control', 'no-store');
+      c.header('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
+      c.header('Expires', '0');
+    }
+    c.header('X-Cache', 'MISS');
+    c.header('ETag', etag);
+    return c.html(source);
+  };
+}
+
+export default fallback;

package/api/src/middlewares/hono/pipeline.ts

@@ -0,0 +1,73 @@
+// Phase 1 (express→hono) — the native route group middleware pipeline.
+//
+// Assembled in the SAME order as the legacy express app shell
+// (service.ts buildNodeHandler: cookie→json→urlencoded→cors→xss→csrf→ensureI18n
+// →cdn→context). hono parses cookies (hono/cookie) and the body (xss is the
+// single body read-point) on demand, so there is no separate cookie/json/
+// urlencoded middleware.
+//
+// IMPORTANT — scoping (design §2 + §7 risk "回环桥 catch-all 与 native 路由遮蔽"):
+// the pipeline is applied SCOPED to each migrated route prefix
+// (`native.use('/api/<domain>/*', mw)`), NOT globally (`use('*')`). A global
+// `use('*')` would run for EVERY request — including those that fall through to
+// the catch-all bridge — double-sourcing cors, consuming the raw body (breaking
+// the Stripe webhook), and resolving the tenant twice. Scoping keeps the bridge
+// path entirely free of native middleware (verified empirically + by the Phase 0
+// single-cors / raw-body invariants). As Phase 3 migrates a domain, it calls
+// mountNativeGroup(native, '/api/<domain>', register) so the SAME pipeline covers
+// that domain's routes and nothing else.
+import type { Hono, MiddlewareHandler } from 'hono';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { cors } from 'hono/cors';
+import { xss } from './xss';
+import { csrf } from './csrf';
+import { cdn } from './cdn';
+import { ensureI18n, contextMiddleware } from './context';
+import { isTestEnv } from '../../libs/env';
+
+// The full app-shell pipeline (single instances, reused across prefixes). This
+// module — and therefore csrf/cdn/context (which import @blocklet/sdk/lib/util/*
+// the CF worker shim does not map) — is only reachable from the NODE host
+// (service.ts getHonoApp); the CF worker mounts resources via the import-light
+// resource-mount.ts, so it never pulls these in.
+const sharedPipeline: MiddlewareHandler[] = [cors(), xss(), csrf(), ensureI18n(), cdn(), contextMiddleware()];
+
+/** The full app-shell middleware array — the node host's appShell for mountResourceGroup. */
+export function fullPipeline(): MiddlewareHandler[] {
+  return sharedPipeline;
+}
+
+/**
+ * Apply the native app-shell pipeline scoped to a route prefix, then register
+ * that group's routes. `prefix` is a path like '/api/customers' (no trailing
+ * slash); the pipeline is bound to `${prefix}/*`, which hono matches for both
+ * the bare prefix and its sub-paths but for nothing outside it.
+ */
+export function mountNativeGroup(native: Hono, prefix: string, register: (native: Hono) => void): void {
+  for (const mw of sharedPipeline) {
+    native.use(`${prefix}/*`, mw);
+  }
+  register(native);
+}
+
+export function configureNativePipeline(native: Hono): void {
+  // Phase 1 production: the native group has no business routes yet (DID-Connect
+  // in Phase 2, resource routes in Phase 3); every request still falls through
+  // to the express bridge. The only native route is a test-only diagnostic that
+  // exercises the full chain (cors→xss→csrf→ensureI18n→cdn→context) end-to-end.
+  if (isTestEnv()) {
+    mountNativeGroup(native, '/api/__e2e', (n) => {
+      const echo = (c: any) =>
+        c.json({
+          body: c.get('sanitizedBody') ?? null,
+          query: c.req.query('q') ?? null,
+          user: c.get('user') ?? null,
+          locale: c.get('locale') ?? null,
+        });
+      n.get('/api/__e2e/echo', echo);
+      n.post('/api/__e2e/echo', echo);
+    });
+  }
+}
+
+export default configureNativePipeline;

package/api/src/middlewares/hono/resource-mount.ts

@@ -0,0 +1,42 @@
+// Phase 4 (express→hono) — resource-domain mounting, split out of pipeline.ts so
+// it stays import-light for the CF worker bundle.
+//
+// The CF worker reaches this module via service.http.resourceRoutes →
+// routes/hono → mountResourceGroup. It must NOT statically import the full
+// app-shell middleware (csrf/cdn/ensureI18n/contextMiddleware), because those pull
+// @blocklet/sdk/lib/util/* subpaths the worker's blocklet-sdk shim does not map —
+// and the worker runs a LITE app-shell anyway (it owns cors + tenant). So this
+// module imports ONLY xss (the routes depend on it to populate sanitizedBody) plus
+// the resource-level livemode/baseCurrency middleware. The node host injects its
+// full app-shell array via the `appShell` option (built in pipeline.ts).
+import type { Hono, MiddlewareHandler } from 'hono';
+import { xss } from './xss';
+
+// LITE app-shell — the worker default. Only xss (self-skips the Stripe raw-body
+// path via RAW_BODY_PREFIXES); cors/csrf/cdn/i18n/context are provided by the
+// worker (cors + tenant) or intentionally absent (the worker never ran csrf/cdn).
+const litePipeline: MiddlewareHandler[] = [xss()];
+
+/**
+ * Mount a RESOURCE domain — the app-shell middleware (default LITE; the node host
+ * passes its full pipeline via `opts.appShell`) + the resource-level livemode
+ * middleware (routes/index.ts:49 parity) + (for the 5 domains that need it)
+ * loadBaseCurrency, all scoped to `${prefix}/*`, then the routes. Middleware order
+ * mirrors express: app-shell → livemode → [baseCurrency] → route.
+ */
+export function mountResourceGroup(
+  native: Hono,
+  prefix: string,
+  subApp: Hono,
+  opts: { baseCurrency?: boolean; appShell?: MiddlewareHandler[] } = {}
+): void {
+  // eslint-disable-next-line global-require
+  const { livemode, loadBaseCurrency } = require('./resource');
+  const appShell = opts.appShell ?? litePipeline;
+  for (const mw of appShell) native.use(`${prefix}/*`, mw);
+  native.use(`${prefix}/*`, livemode());
+  if (opts.baseCurrency) native.use(`${prefix}/*`, loadBaseCurrency());
+  native.route(prefix, subApp); // sub-app routes are relative to the prefix
+}
+
+export default mountResourceGroup;

package/api/src/middlewares/hono/resource.ts

@@ -0,0 +1,63 @@
+// Phase 3 (express→hono) — resource-route prerequisite middleware, the hono fork
+// of the two router-level middlewares in routes/index.ts:
+//   ① livemode (GLOBAL): routes/index.ts:49 — req.livemode = … for every resource
+//      route. Honors ?livemode, then a CF-prefilled value, then PAYMENT_LIVEMODE.
+//   ② loadBaseCurrency (SELECTIVE): routes/index.ts:86 — only 5 domains
+//      (checkout-sessions / donations / payment-links / prices / products).
+// The baseCurrencyCache + lazy PaymentCurrency.addHook registration are
+// framework-agnostic and preserved verbatim.
+import type { MiddlewareHandler } from 'hono';
+import { paymentLivemode } from '../../libs/env';
+import { PaymentCurrency } from '../../store/models/payment-currency';
+
+/** ① livemode — global across all native resource routes (parity with routes/index.ts:49). */
+export function livemode(): MiddlewareHandler {
+  return (c, next) => {
+    const q = c.req.query('livemode');
+    if (q !== undefined && q !== '') {
+      try {
+        c.set('livemode', !!JSON.parse(String(q)));
+      } catch {
+        c.set('livemode', true);
+      }
+    } else {
+      // No upstream prefill on hono (unlike CF createExpressReq); fall back to the
+      // env var, defaulting to livemode=true unless PAYMENT_LIVEMODE=false.
+      c.set('livemode', paymentLivemode());
+    }
+    return next();
+  };
+}
+
+// Lazy base-currency cache with TTL (invalidated on PaymentCurrency update/destroy).
+const baseCurrencyCache = new Map<string, { data: any; expires: number }>();
+const BASE_CURRENCY_TTL = 5 * 60_000;
+let baseCurrencyHooksRegistered = false;
+function ensureBaseCurrencyHooks() {
+  if (baseCurrencyHooksRegistered) return;
+  baseCurrencyHooksRegistered = true;
+  PaymentCurrency.addHook('afterUpdate', 'invalidateBaseCurrencyCache', () => baseCurrencyCache.clear());
+  PaymentCurrency.addHook('afterDestroy', 'invalidateBaseCurrencyCacheOnDelete', () => baseCurrencyCache.clear());
+}
+
+/** ② loadBaseCurrency — only for the 5 domains that read c.get('baseCurrency'). */
+export function loadBaseCurrency(): MiddlewareHandler {
+  return async (c, next) => {
+    ensureBaseCurrencyHooks();
+    const livemodeVal = c.get('livemode');
+    const key = `base_${livemodeVal}`;
+    const cached = baseCurrencyCache.get(key);
+    if (cached && cached.expires > Date.now()) {
+      c.set('baseCurrency', cached.data);
+    } else {
+      const baseCurrency = await PaymentCurrency.findOne({
+        where: { is_base_currency: true, livemode: livemodeVal },
+      });
+      c.set('baseCurrency', baseCurrency);
+      if (baseCurrency) {
+        baseCurrencyCache.set(key, { data: baseCurrency, expires: Date.now() + BASE_CURRENCY_TTL });
+      }
+    }
+    return next();
+  };
+}

package/api/src/middlewares/hono/security.ts

@@ -0,0 +1,214 @@
+// Phase 1 (express→hono) — hono fork of api/src/libs/security.ts authenticate().
+//
+// Behavior is identical to the express version; the plumbing changes:
+//   - req.user= / req.customer= / req.doc=  → c.set('user'|'customer'|'doc', ...)
+//   - mine mode: req.query.customer_id = id  → c.set('customer_id', id) (hono query
+//     is immutable; routes read c.get('customer_id') ?? c.req.query('customer_id')
+//     so a forged ?customer_id cannot bypass the verified injection — design §7).
+//   - the express Bearer branch MUTATED req.headers['x-user-did'] then re-read it;
+//     hono headers are immutable, so the resolved identity is carried in LOCALS
+//     (userDid/userRole/...) instead — same cascade, no header mutation.
+//   - component-sig verify needs an express-req shape for getVerifyData(); a thin
+//     shim is built from the context (body = the sanitized body, xss ran first).
+import type { MiddlewareHandler } from 'hono';
+import type { Model } from 'sequelize';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { getVerifyData, verify } from '@blocklet/sdk/lib/util/verify-sign';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { verifyLoginToken } from '@blocklet/sdk/lib/util/verify-session';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { getWallet } from '@blocklet/sdk/lib/wallet';
+import { isDevelopmentEnv, enableDevFakeAuth } from '../../libs/env';
+import { Customer } from '../../store/models/customer';
+
+// Phase 13b parity: lazy wallet — getWallet() needs BLOCKLET_APP_PK which a bare
+// host lacks; only the embed branch uses it.
+let cachedWallet: ReturnType<typeof getWallet> | undefined;
+const wallet = () => {
+  cachedWallet ??= getWallet();
+  return cachedWallet;
+};
+
+type PermissionSpec<T extends Model> = {
+  component?: boolean;
+  roles?: string[];
+  record?: {
+    model: T;
+    field: string;
+    findById?: (id: string) => Promise<T | null>;
+  };
+  mine?: boolean;
+  embed?: boolean;
+  ensureLogin?: boolean;
+};
+
+export function authenticate<T extends Model>({
+  component,
+  roles,
+  record,
+  mine,
+  embed,
+  ensureLogin,
+}: PermissionSpec<T>): MiddlewareHandler {
+  return async (c, next) => {
+    // Dev-only bypass (NODE_ENV=development AND ENABLE_DEV_FAKE_AUTH=1 AND the
+    // x-dev-fake-did header). Production never sets ENABLE_DEV_FAKE_AUTH.
+    if (isDevelopmentEnv() && enableDevFakeAuth()) {
+      const devDid = c.req.header('x-dev-fake-did');
+      if (devDid) {
+        c.set('user', {
+          did: devDid,
+          role: 'owner',
+          provider: 'dev',
+          fullName: 'dev-fake-user',
+          walletOS: '',
+          via: 'dev',
+        });
+        return next();
+      }
+    }
+
+    // Identity carried in LOCALS (hono headers are immutable). Seed from the
+    // BS-injected x-user-* headers; the Bearer branch may override.
+    let userDid = c.req.header('x-user-did');
+    let userRole = c.req.header('x-user-role');
+    let userProvider = c.req.header('x-user-provider');
+    let userFullname = c.req.header('x-user-fullname');
+    let userWalletOs = c.req.header('x-user-wallet-os');
+
+    // Authenticate by Authorization: Bearer <login-token> (local JWT verify, no
+    // HTTP callback) when BS did not inject x-user-did (tunnel bypass).
+    const authHeader = c.req.header('authorization');
+    if (authHeader && /^Bearer\s+/i.test(authHeader) && !userDid) {
+      const token = authHeader.replace(/^Bearer\s+/i, '').trim();
+      if (token) {
+        const session = await verifyLoginToken({ token, strictMode: false }).catch(() => null);
+        if (session?.did) {
+          const canonicalDid = session.did.startsWith('did:abt:') ? session.did : `did:abt:${session.did}`;
+          userDid = canonicalDid;
+          userRole = `blocklet-${session.role || 'user'}`;
+          userProvider = session.provider || 'wallet';
+          userFullname = encodeURIComponent(session.fullName || '');
+          userWalletOs = session.walletOS || '';
+        }
+      }
+    }
+
+    // authenticate by component call
+    const sig = c.req.header('x-component-sig');
+    if (component && sig) {
+      const url = new URL(c.req.url);
+      const shimReq = {
+        get: (h: string) => c.req.header(h),
+        body: c.get('sanitizedBody') ?? {},
+        method: c.req.method,
+        originalUrl: url.pathname + url.search,
+        query: c.req.query(),
+      };
+      const { data } = getVerifyData(shimReq as any, 'component');
+      const verified = await verify(data, sig);
+      if (!verified) {
+        return c.json({ error: 'Invalid signature for component call' }, 401);
+      }
+      const componentDid = c.req.header('x-component-did') as string;
+      c.set('user', {
+        did: componentDid,
+        role: 'owner',
+        provider: 'wallet',
+        fullName: componentDid,
+        walletOS: '',
+        via: 'api',
+      });
+      return next();
+    }
+
+    // authenticate by authToken for embed
+    const embedToken = c.req.query('authToken') || '';
+    const embedId = c.req.param('id') || c.req.query('subscription_id') || '';
+    if (embed && embedToken && embedId) {
+      // next() is intentionally OUTSIDE the try: the try only guards the
+      // signature verification, never the downstream route (awaiting next here
+      // would wrongly report route errors as embed-auth failures — parity with
+      // the express version, which does not await next()).
+      let embedOk = false;
+      try {
+        const w = wallet();
+        const verified = await w.verify(embedId, embedToken);
+        if (!verified) {
+          return c.json({ error: `Invalid signature for embed: ${embedId}` }, 401);
+        }
+        c.set('user', {
+          did: w.address,
+          role: 'owner',
+          provider: 'wallet',
+          fullName: 'embed',
+          walletOS: '',
+          via: 'embed',
+        });
+        embedOk = true;
+      } catch (err: any) {
+        return c.json({ error: `Invalid signature for embed: ${embedId}: ${err.message}` }, 401);
+      }
+      if (embedOk) return next();
+    }
+
+    if (userDid) {
+      const role = (userRole || '').replace('blocklet-', '') || 'guest';
+      const user = {
+        did: userDid,
+        role,
+        provider: userProvider as string,
+        fullName: decodeURIComponent(userFullname || ''),
+        walletOS: userWalletOs as string,
+        via: 'dashboard',
+      };
+      c.set('user', user);
+
+      // authenticate by session user role
+      if (roles) {
+        if (roles.includes(user.role)) {
+          return next();
+        }
+      }
+
+      if (ensureLogin) {
+        user.via = 'api';
+        c.set('user', user);
+        return next();
+      }
+
+      if (mine) {
+        const customer = await Customer.findOne({ where: { did: user.did } });
+        if (customer) {
+          c.set('customer', customer);
+          // hono query is immutable — inject the VERIFIED id into context so a
+          // forged ?customer_id=<other> cannot bypass the mine check.
+          c.set('customer_id', customer.id);
+          return next();
+        }
+      }
+
+      // authenticate by record owner
+      if (record) {
+        const { model, field = 'customer_id', findById } = record;
+        const id = c.req.param('id') as string;
+        const doc: T | null =
+          findById && typeof findById === 'function' ? await findById(id) : await (model as any).findByPk(id);
+        if (doc && doc[field as keyof T]) {
+          const customer = await Customer.findOne({ where: { did: user.did } });
+          c.set('doc', doc);
+          c.set('customer', customer);
+          if (customer && customer.id === doc[field as keyof T]) {
+            user.via = 'portal';
+            c.set('user', user);
+            return next();
+          }
+        }
+      }
+    }
+
+    return c.json({ error: 'Not authorized to perform this action' }, 403);
+  };
+}
+
+export default authenticate;