hub/gateway/server.mjs · aaronrene/knowtation — MuseHub

aaronrene / knowtation public

server.mjs

3,540 lines 140.5 KB

Raw

sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 16 hours ago

1	/**
2	* Knowtation Hub Gateway — OAuth (Google/GitHub) + proxy to ICP canister with X-User-Id.
3	* For hosted product: user logs in here; all /api/* requests are proxied to canister with proof.
4	* Run: node server.mjs
5	* Env: SESSION_SECRET, CANISTER_URL, HUB_BASE_URL; optional GOOGLE_, GITHUB_, HUB_UI_ORIGIN, GATEWAY_PORT.
6	*/
7
8	import crypto from 'crypto';
9	import fs from 'fs';
10	import path from 'path';
11	import { fileURLToPath } from 'url';
12	import dotenv from 'dotenv';
13	import express from 'express';
14	import cookieParser from 'cookie-parser';
15	import jwt from 'jsonwebtoken';
16	import passport from 'passport';
17	import { Strategy as GoogleStrategy } from 'passport-google-oauth20';
18	import { Strategy as GitHubStrategy } from 'passport-github2';
19	import { stripeWebhookHandler, createCheckoutSession, createPortalSession } from './billing-stripe.mjs';
20	import { handleBillingSummary } from './billing-http.mjs';
21	import { isSubscriptionPriceId, isPackPriceId, priceIdFromTierShorthand, billingEnforced, MONTHLY_INCLUDED_CENTS_BY_TIER } from './billing-constants.mjs';
22	import { recordIndexingTokensAfterBridgeIndex } from './billing-index-usage.mjs';
23	import { runBillingGate } from './billing-middleware.mjs';
24	import { mergeHostedNoteBodyForCanister, isPostApiV1Notes, isNoteWriteRequest } from './apply-note-provenance.mjs';
25	import { deriveFacetsFromCanisterNotes, materializeListFrontmatter } from './note-facets.mjs';
26	import { applyGatewayCors } from './cors-middleware.mjs';
27	import { upstreamPathAndQuery, pathPartNoQuery, effectiveRequestPath } from './request-path.mjs';
28	import { applyScopeFilterToNotes } from '../lib/scope-filter.mjs';
29	import { createMetadataBulkHandlers } from './metadata-bulk-canister.mjs';
30	import { filterUpstreamResponseHeadersForDecodedBody } from './upstream-response-headers.mjs';
31	import { loadProposalRubric } from '../../lib/hub-proposal-rubric.mjs';
32	import { commitImageToRepo, validateImageExtension, validateMagicBytes } from '../../lib/github-commit-image.mjs';
33	import { parseMultipartFile } from './parse-multipart.mjs';
34	import { proposalPolicyEnvLocked } from '../../lib/hub-proposal-policy.mjs';
35	import {
36	loadHostedProposalLlmPrefs,
37	mergeHostedProposalLlmPrefs,
38	effectiveHostedEvaluationRequired,
39	effectiveHostedReviewHints,
40	effectiveHostedEnrich,
41	} from './proposal-llm-store.mjs';
42	import { augmentProposalEvaluationBodyForCanister } from './proposal-evaluation-canister-body.mjs';
43	import { augmentProposalCreateForHosted } from './proposal-create-hosted-body.mjs';
44	import { maybeScheduleHostedProposalReviewHints } from './proposal-review-hints-async.mjs';
45	import { proposalDataForHostedReviewHintsFromCreate } from './proposal-hints-create-context.mjs';
46	import { runHostedProposalEnrichAndPost } from './proposal-enrich-hosted.mjs';
47	import { isAttestationConfigured, createAttestation, verifyAttestation, verifyWithIcp, anchorPendingAttestations } from './attest-store.mjs';
48	import { loadBillingDb, mutateBillingDb } from './billing-store.mjs';
49	import { normalizeBillingUser, defaultUserRecord } from './billing-logic.mjs';
50	import {
51	mergeConsolidateRequestBodyWithBillingDefaults,
52	validateHostedSettingsConsolidationAdvanced,
53	} from '../../lib/hosted-consolidation-advanced.mjs';
54	import {
55	parseMuseConfigFromEnv,
56	resolveExternalRefForApprove,
57	proposalIdFromApprovePath,
58	fetchMuseProxiedGet,
59	} from '../../lib/muse-thin-bridge.mjs';
60	import { exportNoteRecordToContent } from '../../lib/export.mjs';
61	import { canisterAuthHeaders as canisterAuthHeadersFromEnv } from './canister-auth-headers.mjs';
62	import {
63	issueRefreshCookie,
64	createRefreshHandler,
65	createLogoutHandler,
66	refreshCookieOptions,
67	} from '../auth-session.mjs';
68	import {
69	createGatewayRefreshStore,
70	pruneRefreshTokens as pruneGatewayRefreshTokens,
71	} from './refresh-token-store.mjs';
72	import { createScoolingNoteOutlineSmokeRouter } from './scooling-note-outline-smoke.mjs';
73	import { createScoolingWriteBackSmokeRouter } from './scooling-write-back-smoke.mjs';
74	import { buildNoteOutline } from '../../lib/note-outline.mjs';
75	import { buildDocumentTree } from '../../lib/document-tree.mjs';
76	import { buildSectionSource } from '../../lib/section-source.mjs';
77	import { normalizeMetadataFacets } from '../../lib/vault.mjs';
78
79	// Safe when bundled (e.g. Netlify Functions CJS) where import.meta may be undefined
80	let projectRoot;
81	try {
82	const __dirname = path.dirname(fileURLToPath(import.meta.url));
83	projectRoot = path.resolve(__dirname, '..', '..');
84	} catch (_) {
85	projectRoot = process.cwd();
86	}
87	const envPath = path.join(projectRoot, '.env');
88	if (fs.existsSync(envPath)) dotenv.config({ path: envPath });
89
90	const PORT = parseInt(process.env.GATEWAY_PORT \|\| process.env.PORT \|\| '3340', 10);
91	const BASE_URL = process.env.HUB_BASE_URL \|\| `http://localhost:${PORT}`;
92
93	// AIR Improvement D: when ATTESTATION_SECRET is set and no explicit AIR endpoint
94	// is provided, point AIR at this gateway's own /api/v1/attest route.
95	if (
96	process.env.ATTESTATION_SECRET &&
97	process.env.ATTESTATION_SECRET.length >= 32 &&
98	!process.env.KNOWTATION_AIR_ENDPOINT
99	) {
100	process.env.KNOWTATION_AIR_ENDPOINT = `${BASE_URL}/api/v1/attest`;
101	console.log('[gateway] AIR auto-configured: KNOWTATION_AIR_ENDPOINT =', process.env.KNOWTATION_AIR_ENDPOINT);
102	}
103	const CANISTER_URL = (process.env.CANISTER_URL \|\| '').replace(/\/$/, '');
104	const CANISTER_AUTH_SECRET = process.env.CANISTER_AUTH_SECRET \|\| '';
105	const BRIDGE_URL = (process.env.BRIDGE_URL \|\| '').replace(/\/$/, '');
106	if (BRIDGE_URL) {
107	try {
108	const u = new URL(BRIDGE_URL);
109	if (u.protocol !== 'http:' && u.protocol !== 'https:') {
110	throw new Error('BRIDGE_URL must use http: or https:');
111	}
112	} catch (e) {
113	console.error(
114	'[gateway] BRIDGE_URL must be an absolute URL with scheme (no path after host), e.g. https://your-bridge.netlify.app. Got:',
115	JSON.stringify(BRIDGE_URL),
116	e.message \|\| e,
117	);
118	process.exit(1);
119	}
120	}
121	const HUB_UI_ORIGIN = (process.env.HUB_UI_ORIGIN \|\| BASE_URL).replace(/\/$/, '');
122	const SESSION_SECRET = process.env.SESSION_SECRET \|\| process.env.HUB_JWT_SECRET;
123	const JWT_EXPIRY = process.env.HUB_JWT_EXPIRY \|\| '24h';
124
125	// Optional: comma-separated list of user IDs (e.g. google:123,github:456) who get role admin on hosted. Others get member.
126	const HUB_ADMIN_USER_IDS = (process.env.HUB_ADMIN_USER_IDS \|\| '')
127	.split(',')
128	.map((s) => s.trim())
129	.filter(Boolean);
130	const adminUserIdsSet = new Set(HUB_ADMIN_USER_IDS);
131
132	function roleForSub(sub) {
133	return sub && adminUserIdsSet.has(sub) ? 'admin' : 'member';
134	}
135
136	function canisterAuthHeaders() {
137	return canisterAuthHeadersFromEnv();
138	}
139
140	passport.serializeUser((user, done) => done(null, user));
141	passport.deserializeUser((obj, done) => done(null, obj));
142
143	if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
144	passport.use(
145	new GoogleStrategy(
146	{
147	clientID: process.env.GOOGLE_CLIENT_ID,
148	clientSecret: process.env.GOOGLE_CLIENT_SECRET,
149	callbackURL: `${BASE_URL}/auth/callback/google`,
150	},
151	(_accessToken, _refreshToken, profile, done) => {
152	return done(null, { provider: 'google', id: profile.id, displayName: profile.displayName ?? '' });
153	}
154	)
155	);
156	}
157	if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
158	passport.use(
159	new GitHubStrategy(
160	{
161	clientID: process.env.GITHUB_CLIENT_ID,
162	clientSecret: process.env.GITHUB_CLIENT_SECRET,
163	callbackURL: `${BASE_URL}/auth/callback/github`,
164	},
165	(_accessToken, _refreshToken, profile, done) => {
166	return done(null, { provider: 'github', id: profile.id, displayName: profile.displayName ?? profile.username ?? '' });
167	}
168	)
169	);
170	}
171
172	function userId(user) {
173	if (!user \|\| !user.provider \|\| !user.id) return null;
174	return `${user.provider}:${user.id}`;
175	}
176
177	function issueToken(user) {
178	const sub = userId(user);
179	if (!sub) return null;
180	const role = roleForSub(sub);
181	return jwt.sign(
182	{
183	sub,
184	provider: user.provider,
185	id: user.id,
186	name: user.displayName ?? '',
187	role,
188	},
189	SESSION_SECRET,
190	{ expiresIn: JWT_EXPIRY }
191	);
192	}
193
194	function verifyToken(token) {
195	try {
196	const payload = jwt.verify(token, SESSION_SECRET);
197	return payload.sub ?? null;
198	} catch (_) {
199	return null;
200	}
201	}
202
203	/**
204	* Verify the token and return the full decoded payload, or null if invalid/expired.
205	* Used only by the session-introspection endpoint; callers that only need `sub` use verifyToken.
206	* @param {string} token
207	* @returns {object\|null}
208	*/
209	function decodeVerifiedToken(token) {
210	try {
211	return jwt.verify(token, SESSION_SECRET);
212	} catch (_) {
213	return null;
214	}
215	}
216
217	/**
218	* Derive the set of API scopes from a role string.
219	* This is the C7 → C4 bridge: Scooling can read `scopes` today; when explicit per-user
220	* scope management (C4) is wired in, this function will be replaced with a real lookup
221	* without changing the C7 response shape.
222	* @param {string} role - 'admin' \| 'member'
223	* @returns {string[]}
224	*/
225	function scopesForRole(role) {
226	if (role === 'admin') return ['vault:read', 'vault:write', 'admin'];
227	return ['vault:read', 'vault:write'];
228	}
229
230	/**
231	* Re-mint a short-lived access token from a `sub` alone (used by POST /api/v1/auth/refresh,
232	* which only knows the user id carried by the refresh-token record). The `sub` is the canonical
233	* `provider:id`, so provider/id are reconstructed from it and the role is re-derived from the
234	* current admin allowlist — a refreshed token always reflects the latest role, exactly like
235	* login. Display name is omitted (cosmetic; the UI reads it from /settings).
236	* @param {string} sub
237	* @returns {string\|null} signed JWT, or null when sub is missing
238	*/
239	function issueAccessTokenForSub(sub) {
240	if (!sub \|\| typeof sub !== 'string') return null;
241	const idx = sub.indexOf(':');
242	const provider = idx > 0 ? sub.slice(0, idx) : '';
243	const id = idx > 0 ? sub.slice(idx + 1) : sub;
244	return jwt.sign(
245	{ sub, provider, id, name: '', role: roleForSub(sub) },
246	SESSION_SECRET,
247	{ expiresIn: JWT_EXPIRY }
248	);
249	}
250
251	const IMAGE_PROXY_TOKEN_TTL_SECONDS = 300;
252
253	function signImageProxyToken(secret, uid) {
254	const exp = Math.floor(Date.now() / 1000) + IMAGE_PROXY_TOKEN_TTL_SECONDS;
255	const payload = `img\0${uid}\0${exp}`;
256	const sig = crypto.createHmac('sha256', secret).update(payload).digest('base64url');
257	return `${exp}.${Buffer.from(uid).toString('base64url')}.${sig}`;
258	}
259
260	function verifyImageProxyToken(secret, token) {
261	if (typeof token !== 'string') return null;
262	const parts = token.split('.');
263	if (parts.length !== 3) return null;
264	const [expStr, uidB64, sig] = parts;
265	const exp = parseInt(expStr, 10);
266	if (!exp \|\| Math.floor(Date.now() / 1000) > exp) return null;
267	let uid;
268	try { uid = Buffer.from(uidB64, 'base64url').toString(); } catch (_) { return null; }
269	if (!uid) return null;
270	const payload = `img\0${uid}\0${exp}`;
271	const expected = crypto.createHmac('sha256', secret).update(payload).digest('base64url');
272	const sigBuf = Buffer.from(sig);
273	const expectedBuf = Buffer.from(expected);
274	if (sigBuf.length !== expectedBuf.length \|\| !crypto.timingSafeEqual(sigBuf, expectedBuf)) return null;
275	return uid;
276	}
277
278	const app = express();
279	// Trust the first downstream proxy so express-rate-limit (and any future IP-based middleware)
280	// reads the real client IP from X-Forwarded-For instead of the CDN/load-balancer address.
281	app.set('trust proxy', 1);
282
283	// Remove X-Powered-By: Express — leaking server technology is unnecessary attack surface.
284	app.disable('x-powered-by');
285
286	// Netlify rewrites /* -> /.netlify/functions/gateway/:splat, so the function may receive
287	// a path like /.netlify/functions/gateway/api/v1/notes. Express would not match /api/v1/* routes.
288	const NETLIFY_GW_PREFIX = '/.netlify/functions/gateway';
289	app.use((req, _res, next) => {
290	const raw = req.url \|\| '/';
291	const q = raw.indexOf('?');
292	const pathPart = q >= 0 ? raw.slice(0, q) : raw;
293	const queryPart = q >= 0 ? raw.slice(q) : '';
294	if (pathPart === NETLIFY_GW_PREFIX \|\| pathPart.startsWith(`${NETLIFY_GW_PREFIX}/`)) {
295	const rest =
296	pathPart === NETLIFY_GW_PREFIX ? '/' : pathPart.slice(NETLIFY_GW_PREFIX.length) \|\| '/';
297	const nextUrl = rest + queryPart;
298	req.url = nextUrl;
299	// Express may set originalUrl to the internal function path; keep it aligned with req.path.
300	req.originalUrl = nextUrl;
301	delete req._parsedUrl;
302	delete req._parsedOriginalUrl;
303	}
304	next();
305	});
306
307	app.use(cookieParser());
308	app.post('/api/v1/billing/webhook', express.raw({ type: 'application/json' }), (req, res) => {
309	stripeWebhookHandler(req, res);
310	});
311	app.use(express.json({ limit: '10mb' }));
312	app.use(passport.initialize());
313
314	// CORS: production MUST set HUB_CORS_ORIGIN (apex + www) for credentialed-style responses.
315	// If unset, we use * and omit Allow-Credentials — otherwise browsers block (* + credentials = Failed to fetch).
316	// See hub/gateway/cors-middleware.mjs.
317	const corsOrigins = process.env.HUB_CORS_ORIGIN
318	? process.env.HUB_CORS_ORIGIN.split(',').map((o) => o.trim()).filter(Boolean)
319	: [];
320	app.use((req, res, next) => {
321	applyGatewayCors(res, req.get('Origin'), corsOrigins);
322	next();
323	});
324
325	// Persistent sessions (refresh-token rotation), hosted edition. The durable, hashed refresh
326	// token is delivered as an HttpOnly cookie; the security logic lives in
327	// hub/lib/refresh-token-core.mjs via the blob-backed store below (shared with self-hosted).
328	const refreshStore = createGatewayRefreshStore();
329
330	/**
331	* Cookie policy for the hosted refresh token.
332	* - When the UI and gateway share an origin (HUB_CORS_ORIGIN unset), the cookie is first-party
333	* and SameSite=Lax is correct and most robust.
334	* - When HUB_CORS_ORIGIN is set the UI is on another origin, so the credentialed cross-site
335	* request requires SameSite=None (which forces Secure). NOTE: a cross-site cookie is only
336	* delivered reliably when the gateway is a subdomain of the UI's registrable domain (e.g.
337	* UI knowtation.store + gateway api.knowtation.store); browsers increasingly block
338	* unrelated third-party cookies. Same-origin (single origin for UI + API) is recommended.
339	* Scoped to the auth path so the cookie is only ever sent to /api/v1/auth endpoints.
340	*/
341	function refreshCookiePolicy() {
342	const crossOrigin = corsOrigins.length > 0;
343	return refreshCookieOptions({
344	secure: crossOrigin \|\| BASE_URL.startsWith('https://'),
345	sameSite: crossOrigin ? 'none' : 'lax',
346	maxAgeMs: 90 * 24 * 60 * 60 * 1000,
347	});
348	}
349
350	/**
351	* Issue the HttpOnly refresh cookie at the end of a successful OAuth login. Best-effort: a
352	* refresh-store write failure must never block login (the access token still works).
353	* @param {import('express').Response} res
354	* @param {import('express').Request} req
355	* @param {string\|null} sub
356	*/
357	async function issueRefreshCookieSafe(res, req, sub) {
358	if (!sub) {
359	console.warn('[gateway] refresh cookie skipped: no sub resolved from req.user');
360	return;
361	}
362	try {
363	await issueRefreshCookie(res, {
364	store: refreshStore,
365	sub,
366	cookieOptions: refreshCookiePolicy,
367	meta: { ua: String(req.headers['user-agent'] \|\| '').slice(0, 256) },
368	});
369	console.info('[gateway] refresh cookie issued for sub=%s', sub);
370	} catch (err) {
371	// Login still proceeds with the access token even if the refresh store is unavailable, but
372	// the failure MUST be surfaced — swallowing it silently made a persistent-login outage
373	// undiagnosable. `authBlobPresent` distinguishes the two failure modes:
374	// false → the Netlify Blob was not provisioned for this invocation, so the store fell back
375	// to a file write that fails on the read-only function FS;
376	// true → the blob was provisioned but the read/write itself was rejected.
377	const authBlobPresent = Boolean(globalThis.__knowtation_gateway_auth_blob);
378	console.error(
379	'[gateway] refresh cookie FAILED for sub=%s authBlobPresent=%s: %s',
380	sub,
381	authBlobPresent,
382	err && err.stack ? err.stack : (err && err.message) \|\| String(err),
383	);
384	}
385	}
386
387	// Authenticated Hub JSON must not be cached (browser 304 / CDN reuse shows stale frontmatter).
388	app.use('/api/v1', (req, res, next) => {
389	res.set('Cache-Control', 'private, no-store, must-revalidate');
390	next();
391	});
392
393	// Health (no auth) — returns { ok: true }. If a CDN or host wrapper returns usage_exceeded, that is outside this app (check Netlify site / account limits and which commit is deployed).
394	app.get('/health', (_req, res) => res.json({ ok: true }));
395	app.get('/api/v1/health', (_req, res) => res.json({ ok: true }));
396	app.use(createScoolingNoteOutlineSmokeRouter());
397	app.use(createScoolingWriteBackSmokeRouter());
398
399	// Which OAuth providers are configured (no auth)
400	app.get('/api/v1/auth/providers', (_req, res) => {
401	res.json({
402	google: Boolean(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET),
403	github: Boolean(process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET),
404	});
405	});
406
407	// C7 Session introspection — returns the verified identity and derived scopes for the bearer.
408	// Designed for Scooling (cross-origin, Bearer auth) and the Hub UI alike.
409	// GET /api/v1/auth/session → { sub, provider, id, name, role, iat, exp, scopes }
410	// Only reads what is already in the signed JWT — no extra DB call, no data elevation.
411	app.options('/api/v1/auth/session', (_req, res) => res.status(204).end());
412	app.get('/api/v1/auth/session', (req, res) => {
413	const auth = req.headers.authorization;
414	if (!auth \|\| !auth.startsWith('Bearer ')) {
415	return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
416	}
417	const token = auth.slice(7);
418	const payload = decodeVerifiedToken(token);
419	if (!payload \|\| !payload.sub) {
420	return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
421	}
422	return res.json({
423	sub: payload.sub,
424	provider: payload.provider ?? '',
425	id: payload.id ?? '',
426	name: payload.name ?? '',
427	role: payload.role ?? 'member',
428	iat: payload.iat,
429	exp: payload.exp,
430	scopes: scopesForRole(payload.role ?? 'member'),
431	});
432	});
433
434	// Persistent sessions: exchange the HttpOnly refresh cookie for a fresh access token, and real
435	// server-side logout (revokes the refresh token, not just the client cookie). Mounted BEFORE the
436	// bridge/canister proxies so these are handled locally and never forwarded upstream.
437	//
438	// Rate limiting note: an in-memory express-rate-limit is ineffective on Netlify (each function
439	// invocation is isolated, no shared counter) and trips ERR_ERL_* under serverless proxies. Brute
440	// force is bounded instead by edge limits (see hub/gateway/README.md) and, more fundamentally, by
441	// the opaque high-entropy token + rotation/reuse detection in refresh-token-core.mjs.
442	app.options(['/api/v1/auth/refresh', '/api/v1/auth/logout'], (_req, res) => res.status(204).end());
443	app.post(
444	'/api/v1/auth/refresh',
445	createRefreshHandler({
446	store: refreshStore,
447	issueAccessToken: issueAccessTokenForSub,
448	cookieOptions: refreshCookiePolicy,
449	meta: (req) => ({ ua: String(req.headers['user-agent'] \|\| '').slice(0, 256) }),
450	})
451	);
452	app.post(
453	'/api/v1/auth/logout',
454	createLogoutHandler({ store: refreshStore, cookieOptions: refreshCookiePolicy })
455	);
456	// On a persistent gateway (local/Docker/VPS) opportunistically prune dead refresh records at
457	// startup. Skipped on Netlify, where the blob store is provisioned per-invocation and a cold-start
458	// prune would add latency to the first request; rely on rotation/expiry to keep the store small.
459	if (!process.env.NETLIFY) {
460	Promise.resolve()
461	.then(() => pruneGatewayRefreshTokens())
462	.catch(() => { /* best effort; never fatal */ });
463	}
464
465	// Auth: login redirect — plan routes GET /auth/login, GET /auth/callback/google\|github. Preserve invite in state for post-login redirect.
466	// Phase D3: mcp_state query param is passed through OAuth state for MCP authorization flow.
467	// C1/C3 (COMPANION-APP-OAUTH-SERVERSIDE-GATE §6): native_state query param is passed
468	// through OAuth state for the native client authorization flow (prefix "native:").
469	app.get('/auth/login', (req, res, next) => {
470	const provider = (req.query.provider \|\| 'google').toLowerCase();
471	const invite = typeof req.query.invite === 'string' ? req.query.invite.trim() : '';
472	const mcpState = typeof req.query.mcp_state === 'string' ? req.query.mcp_state.trim() : '';
473	const nativeState = typeof req.query.native_state === 'string' ? req.query.native_state.trim() : '';
474	let state;
475	if (mcpState) {
476	state = `mcp:${mcpState}`;
477	} else if (nativeState) {
478	// Prefix distinguishes native auth round-trips from MCP round-trips in the IDP callback.
479	state = `native:${nativeState}`;
480	} else {
481	state = invite \|\| undefined;
482	}
483	if (provider === 'google' && process.env.GOOGLE_CLIENT_ID) {
484	return passport.authenticate('google', { scope: ['profile'], state })(req, res, next);
485	}
486	if (provider === 'github' && process.env.GITHUB_CLIENT_ID) {
487	return passport.authenticate('github', { scope: ['user:email'], state })(req, res, next);
488	}
489	return res.status(400).json({ error: `Unknown or disabled provider: ${provider}`, code: 'BAD_REQUEST' });
490	});
491
492	function postLoginRedirect(token, req) {
493	if (!token) return HUB_UI_ORIGIN + '/hub/?auth_error=1';
494	const invite = typeof req.query.state === 'string' ? req.query.state.trim() : '';
495	let fragment = `token=${encodeURIComponent(token)}`;
496	if (invite && invite.length > 0) fragment += '&invite=' + encodeURIComponent(invite);
497	return `${HUB_UI_ORIGIN}/hub/#${fragment}`;
498	}
499
500	app.get(
501	'/auth/callback/google',
502	passport.authenticate('google', { session: false }),
503	async (req, res) => {
504	const state = typeof req.query.state === 'string' ? req.query.state : '';
505	if (state.startsWith('mcp:') && app._mcpOAuthProvider) {
506	const sub = userId(req.user);
507	if (!sub) return res.status(401).json({ error: 'auth_failed' });
508	return app._mcpOAuthProvider.completeMcpAuthorization(state.slice(4), sub, res);
509	}
510	// C1/C3: native client authorization flow (COMPANION-APP-OAUTH-SERVERSIDE-GATE §6).
511	if (state.startsWith('native:') && app._nativeOAuthProvider) {
512	const sub = userId(req.user);
513	if (!sub) return res.status(401).json({ error: 'auth_failed' });
514	return app._nativeOAuthProvider.completeNativeAuthorization(state.slice(7), sub, res);
515	}
516	const token = issueToken(req.user);
517	await issueRefreshCookieSafe(res, req, userId(req.user));
518	res.redirect(postLoginRedirect(token, req));
519	}
520	);
521	app.get(
522	'/auth/callback/github',
523	passport.authenticate('github', { session: false }),
524	async (req, res) => {
525	const state = typeof req.query.state === 'string' ? req.query.state : '';
526	if (state.startsWith('mcp:') && app._mcpOAuthProvider) {
527	const sub = userId(req.user);
528	if (!sub) return res.status(401).json({ error: 'auth_failed' });
529	return app._mcpOAuthProvider.completeMcpAuthorization(state.slice(4), sub, res);
530	}
531	// C1/C3: native client authorization flow (COMPANION-APP-OAUTH-SERVERSIDE-GATE §6).
532	if (state.startsWith('native:') && app._nativeOAuthProvider) {
533	const sub = userId(req.user);
534	if (!sub) return res.status(401).json({ error: 'auth_failed' });
535	return app._nativeOAuthProvider.completeNativeAuthorization(state.slice(7), sub, res);
536	}
537	const token = issueToken(req.user);
538	await issueRefreshCookieSafe(res, req, userId(req.user));
539	res.redirect(postLoginRedirect(token, req));
540	}
541	);
542
543	// Hub UI may call login under /api/v1/auth for consistency — redirect to /auth (preserve invite for post-login consume)
544	app.get('/api/v1/auth/login', (req, res) => {
545	const provider = (req.query.provider \|\| 'google').toLowerCase();
546	let url = `${BASE_URL}/auth/login?provider=${encodeURIComponent(provider)}`;
547	const invite = typeof req.query.invite === 'string' ? req.query.invite.trim() : '';
548	if (invite) url += '&invite=' + encodeURIComponent(invite);
549	res.redirect(url);
550	});
551
552	// Phase D2/D3: MCP gateway + OAuth 2.1.
553	// MCP requires stateful sessions (SSE, session pool) that are incompatible with Netlify's
554	// serverless function model (26s timeout, no shared memory between invocations).
555	// On Netlify, only the OAuth discovery endpoints are mounted (lightweight, stateless).
556	// The full /mcp session endpoint requires a persistent Express server (local dev, Docker, VPS,
557	// or a dedicated MCP host like Railway/Fly.io). See docs/AGENT-INTEGRATION.md §2 (hosted MCP).
558	if (SESSION_SECRET && !process.env.NETLIFY) {
559	import('./mcp-oauth-provider.mjs').then(async ({ KnowtationOAuthProvider }) => {
560	const { mcpAuthRouter } = await import('@modelcontextprotocol/sdk/server/auth/router.js');
561	const oauthProvider = new KnowtationOAuthProvider({
562	sessionSecret: SESSION_SECRET,
563	baseUrl: BASE_URL,
564	});
565	app._mcpOAuthProvider = oauthProvider;
566	// @modelcontextprotocol/sdk OAuth routes use express-rate-limit behind Nginx. The limiter's
567	// default validations (X-Forwarded-For vs Express trust proxy) still throw ERR_ERL_* on some
568	// Express/SDK mount combinations. Disable express-rate-limit validations for these routes only;
569	// limits stay on; edge limits remain in Nginx (gateway deploy notes in hub/gateway/README.md).
570	const mcpOAuthSdkRateLimitOpts = {
571	rateLimit: { validate: false },
572	};
573	app.use(mcpAuthRouter({
574	provider: oauthProvider,
575	issuerUrl: new URL(BASE_URL),
576	scopesSupported: ['vault:read', 'vault:write', 'vault:admin'],
577	authorizationOptions: mcpOAuthSdkRateLimitOpts,
578	tokenOptions: mcpOAuthSdkRateLimitOpts,
579	clientRegistrationOptions: mcpOAuthSdkRateLimitOpts,
580	revocationOptions: mcpOAuthSdkRateLimitOpts,
581	}));
582	console.log('[gateway] MCP OAuth 2.1 endpoints mounted');
583
584	// C1–C6 (COMPANION-APP-OAUTH-SERVERSIDE-GATE §6): native client OAuth 2.1 endpoints.
585	// The native path issues web-session JWTs (issueToken shape) instead of mcp_access
586	// tokens, uses refresh-token-core for durable rotation, enforces loopback-only
587	// redirect URIs, validates redirect_uri at exchange, and applies a scope ceiling.
588	// Mounted only on the persistent gateway host — same guard as the MCP router.
589	try {
590	const { createNativeOAuthRouter } = await import('./native-oauth-provider.mjs');
591	const { router: nativeRouter, completeNativeAuthorization } = createNativeOAuthRouter({
592	baseUrl: BASE_URL,
593	loginUrl: `${BASE_URL}/auth/login`,
594	issueAccessToken: issueAccessTokenForSub,
595	// C6: grantedScopes resolves the scope ceiling via roleForSub; unknown sub → member.
596	grantedScopes: (sub) => scopesForRole(roleForSub(sub)),
597	// C2/C4: reuse the same durable refresh store as the web session so rotation +
598	// reuse-detection use the same family records. Store is file-backed on this host.
599	refreshStore,
600	});
601	// Bind completeNativeAuthorization so IDP callbacks can reach it (see /auth/callback/*).
602	app._nativeOAuthProvider = { completeNativeAuthorization };
603	app.use('/api/v1/auth/native', nativeRouter);
604	console.log('[gateway] Native OAuth 2.1 endpoints mounted at /api/v1/auth/native');
605
606	// C4: opportunistically prune expired native auth codes at startup.
607	const { pruneExpiredCodes } = await import('./native-as-store.mjs');
608	pruneExpiredCodes().catch(() => { /* best effort; never fatal */ });
609	} catch (e) {
610	console.error('[gateway] Native OAuth router failed to load:', e.message \|\| e);
611	}
612	}).catch((e) => {
613	console.error('[gateway] MCP OAuth router failed to load:', e.message \|\| e);
614	});
615	} else if (SESSION_SECRET && process.env.NETLIFY) {
616	console.log('[gateway] MCP OAuth/session endpoints skipped on Netlify (stateful sessions require persistent server)');
617	}
618
619	if (BRIDGE_URL && CANISTER_URL && !process.env.NETLIFY) {
620	import('./mcp-proxy.mjs').then(({ createMcpProxyRouter }) => {
621	const mcpRouter = createMcpProxyRouter({
622	getUserId,
623	getHostedAccessContext,
624	canisterUrl: CANISTER_URL,
625	canisterAuthSecret: CANISTER_AUTH_SECRET,
626	bridgeUrl: BRIDGE_URL,
627	gatewayApiBaseUrl: BASE_URL.replace(/\/$/, ''),
628	sessionSecret: SESSION_SECRET \|\| '',
629	});
630	app.use('/mcp', mcpRouter);
631	console.log('[gateway] MCP endpoint mounted at /mcp');
632	if (!CANISTER_AUTH_SECRET) {
633	console.warn(
634	'[gateway] MCP /mcp: CANISTER_AUTH_SECRET is empty. Direct canister HTTP calls from hosted MCP (list_notes, get_note, write, enrich; summarize note fetches) send no X-Gateway-Auth and the canister returns GATEWAY_AUTH_REQUIRED. Set the same CANISTER_AUTH_SECRET as the Netlify gateway and as configured on the canister (admin_set_gateway_auth_secret), then pm2 restart with --update-env.'
635	);
636	}
637	}).catch((e) => {
638	console.error('[gateway] MCP proxy failed to load:', e.message \|\| e);
639	});
640	} else if (process.env.NETLIFY) {
641	app.all('/mcp', (_req, res) => {
642	res.status(503).json({
643	error: 'MCP endpoint requires a persistent server. Connect to the dedicated MCP host or use self-hosted deployment.',
644	code: 'MCP_NETLIFY_UNSUPPORTED',
645	docs: 'https://github.com/aaronrene/knowtation/blob/main/docs/AGENT-INTEGRATION.md',
646	});
647	});
648	}
649
650	// Connect GitHub + Back up now: proxy to bridge when BRIDGE_URL is set (single origin for UI)
651	if (BRIDGE_URL) {
652	app.get('/api/v1/auth/github-connect', (req, res) => {
653	const q = new URLSearchParams(req.query).toString();
654	res.redirect(`${BRIDGE_URL}/auth/github-connect${q ? '?' + q : ''}`);
655	});
656	// Browsers send OPTIONS preflight before POST with Authorization + JSON body. The bridge only
657	// registers POST /api/v1/vault/sync, so proxying OPTIONS returns 404 and surfaces as "Failed to fetch".
658	app.all('/api/v1/vault/sync', async (req, res) => {
659	if (req.method === 'OPTIONS') {
660	return res.status(204).end();
661	}
662	const url = BRIDGE_URL + '/api/v1/vault/sync' + (req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '');
663	await proxyTo(BRIDGE_URL, url, req, res);
664	});
665	app.all('/api/v1/vaults/:vaultId', async (req, res) => {
666	if (req.method === 'OPTIONS') {
667	return res.status(204).end();
668	}
669	if (req.method !== 'DELETE') {
670	return res.status(405).json({ error: 'Method not allowed', code: 'METHOD_NOT_ALLOWED' });
671	}
672	if (!(await runBillingGate(req, res, getUserId))) return;
673	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
674	const url =
675	BRIDGE_URL + '/api/v1/vaults/' + encodeURIComponent(req.params.vaultId) + q;
676	await proxyTo(BRIDGE_URL, url, req, res);
677	});
678	app.get('/api/v1/vault/github-status', async (req, res) => {
679	const url = BRIDGE_URL + '/api/v1/vault/github-status' + (req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '');
680	await proxyTo(BRIDGE_URL, url, req, res);
681	});
682	app.post('/api/v1/search', async (req, res) => {
683	if (!(await runBillingGate(req, res, getUserId))) return;
684	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/search', req, res);
685	});
686	app.post('/api/v1/index', async (req, res) => {
687	if (!(await runBillingGate(req, res, getUserId))) return;
688	const uid = getUserId(req);
689	const headers = { ...req.headers, host: new URL(BRIDGE_URL).host };
690	delete headers.origin;
691	delete headers.referer;
692	const opts = { method: 'POST', headers };
693	const payload =
694	req.body === undefined ? undefined : typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
695	if (payload !== undefined) {
696	opts.body = payload;
697	stripStaleOutboundBodyHeaders(headers);
698	}
699	try {
700	const upstream = await fetch(BRIDGE_URL + '/api/v1/index', opts);
701	const body = await upstream.text();
702	if (uid) await recordIndexingTokensAfterBridgeIndex(uid, upstream.status, body);
703	const hop = filterUpstreamResponseHeadersForDecodedBody(upstream.headers.entries());
704	res.status(upstream.status).set(Object.fromEntries(hop));
705	res.send(body);
706	} catch (e) {
707	console.error('Gateway proxy (bridge) error:', e.message);
708	res.status(502).json({ error: 'Bad Gateway', code: 'BAD_GATEWAY' });
709	}
710	});
711	// GET /api/v1/index/status — read-only sidecar describing the last successful
712	// index + whether a background job is currently in flight. Added in May 2026
713	// alongside the auto-routing index path (PR #205) so the Hub UI can render
714	// `Last indexed: N minutes ago` next to the Re-index button.
715	//
716	// Auth scoping happens at the bridge (`requireBridgeAuth` + vault-scoping).
717	// We deliberately DO NOT run `runBillingGate` here — this is a passive read,
718	// not a billable index operation, and the Hub UI calls this on every page
719	// load (so charging would be both incorrect and abusive).
720	//
721	// See `test/gateway-index-status-proxy.test.mjs` for the contract test that
722	// prevents this handler from being silently removed.
723	app.get('/api/v1/index/status', async (req, res) => {
724	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/index/status', req, res);
725	});
726	// Roles & invites: proxy to bridge (bridge has persistent storage)
727	app.get('/api/v1/roles', requireAdmin, async (req, res) => {
728	await proxyTo(BRIDGE_URL, BRIDGE_URL + req.originalUrl, req, res);
729	});
730	app.post('/api/v1/roles', requireAdmin, async (req, res) => {
731	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/roles', req, res);
732	});
733	app.post('/api/v1/roles/evaluator-may-approve', requireAdmin, async (req, res) => {
734	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/roles/evaluator-may-approve', req, res);
735	});
736	app.get('/api/v1/invites', requireAdmin, async (req, res) => {
737	await proxyTo(BRIDGE_URL, BRIDGE_URL + req.originalUrl, req, res);
738	});
739	app.post('/api/v1/invites', requireAdmin, async (req, res) => {
740	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/invites', req, res);
741	});
742	app.delete('/api/v1/invites/:token', requireAdmin, async (req, res) => {
743	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/invites/' + encodeURIComponent(req.params.token), req, res);
744	});
745	app.post('/api/v1/invites/consume', (req, res, next) => {
746	const uid = getUserId(req);
747	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
748	next();
749	}, async (req, res) => {
750	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/invites/consume', req, res);
751	});
752	app.get('/api/v1/workspace', requireAdmin, async (req, res) => {
753	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/workspace', req, res);
754	});
755	app.post('/api/v1/workspace', requireAdmin, async (req, res) => {
756	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/workspace', req, res);
757	});
758	app.get('/api/v1/vault-access', requireAdmin, async (req, res) => {
759	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/vault-access', req, res);
760	});
761	app.post('/api/v1/vault-access', requireAdmin, async (req, res) => {
762	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/vault-access', req, res);
763	});
764	app.get('/api/v1/scope', requireAdmin, async (req, res) => {
765	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/scope', req, res);
766	});
767	app.post('/api/v1/scope', requireAdmin, async (req, res) => {
768	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/scope', req, res);
769	});
770	app.get('/api/v1/hosted-context', async (req, res, next) => {
771	const uid = getUserId(req);
772	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
773	next();
774	}, async (req, res) => {
775	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/hosted-context', req, res);
776	});
777
778	// Memory routes: proxy to bridge (per-user/vault isolation handled by bridge)
779	app.get('/api/v1/memory/:key', async (req, res) => {
780	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
781	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/memory/' + encodeURIComponent(req.params.key) + q, req, res);
782	});
783	app.post('/api/v1/memory/store', async (req, res) => {
784	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/memory/store', req, res);
785	});
786	app.get('/api/v1/memory', async (req, res) => {
787	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
788	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/memory' + q, req, res);
789	});
790	app.post('/api/v1/memory/search', async (req, res) => {
791	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/memory/search', req, res);
792	});
793	app.delete('/api/v1/memory/clear', async (req, res) => {
794	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/memory/clear', req, res);
795	});
796	app.get('/api/v1/memory-stats', async (req, res) => {
797	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/memory-stats', req, res);
798	});
799	// Consolidation routes: proxy to bridge with billing gate on POST
800	app.post('/api/v1/memory/consolidate', async (req, res) => {
801	if (!(await runBillingGate(req, res, getUserId))) return;
802	const uid = getUserId(req);
803	try {
804	const db = await loadBillingDb();
805	const raw = db.users?.[uid] \|\| defaultUserRecord(uid);
806	const u = normalizeBillingUser(raw);
807	req.body = mergeConsolidateRequestBodyWithBillingDefaults(
808	req.body && typeof req.body === 'object' ? req.body : {},
809	u,
810	);
811	} catch (_) {
812	/* fail open: bridge merges with billing file / defaults */
813	}
814	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/memory/consolidate', req, res);
815	});
816	app.get('/api/v1/memory/consolidate/status', async (req, res) => {
817	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/memory/consolidate/status', req, res);
818	});
819
820	// Calendar routes (hosted parity — step 12): proxy read + toggle PATCH to bridge event store.
821	app.get('/api/v1/calendar/timeline', async (req, res) => {
822	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
823	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/calendar/timeline' + q, req, res);
824	});
825	app.get('/api/v1/calendar/agent-context', async (req, res) => {
826	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
827	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/calendar/agent-context' + q, req, res);
828	});
829	app.get('/api/v1/calendar/source-calendars', async (req, res) => {
830	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
831	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/calendar/source-calendars' + q, req, res);
832	});
833	app.patch('/api/v1/calendar/source-calendars/:id', async (req, res) => {
834	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
835	await proxyTo(
836	BRIDGE_URL,
837	BRIDGE_URL + '/api/v1/calendar/source-calendars/' + encodeURIComponent(req.params.id) + q,
838	req,
839	res,
840	);
841	});
842	app.post('/api/v1/calendar/events/import', async (req, res) => {
843	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
844	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/calendar/events/import' + q, req, res);
845	});
846
847	// Flow routes (hosted parity — 7A-L2b): proxy read projections (+ grants when gate on).
848	const isFlowHostedProjectionEnabled = () => {
849	const v = process.env.FLOW_HOSTED_PROJECTION_ENABLED;
850	return v === '1' \|\| v === 'true';
851	};
852	app.get('/api/v1/flows/:id/projection', async (req, res) => {
853	const harness = typeof req.query.harness === 'string' ? req.query.harness.trim() : '';
854	if (harness === 'agent_bundle' && !isFlowHostedProjectionEnabled()) {
855	return res.status(403).json({
856	error: 'Hosted agent_bundle projection disabled',
857	code: 'FLOW_HOSTED_PROJECTION_DISABLED',
858	});
859	}
860	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
861	await proxyTo(
862	BRIDGE_URL,
863	BRIDGE_URL + '/api/v1/flows/' + encodeURIComponent(req.params.id) + '/projection' + q,
864	req,
865	res,
866	);
867	});
868	app.get('/api/v1/flows/external-grants', async (req, res) => {
869	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
870	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/flows/external-grants' + q, req, res);
871	});
872	app.post('/api/v1/flows/:id/external-grants', async (req, res) => {
873	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
874	await proxyTo(
875	BRIDGE_URL,
876	BRIDGE_URL + '/api/v1/flows/' + encodeURIComponent(req.params.id) + '/external-grants' + q,
877	req,
878	res,
879	);
880	});
881	app.delete('/api/v1/flows/external-grants/:grant_id', async (req, res) => {
882	const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
883	await proxyTo(
884	BRIDGE_URL,
885	BRIDGE_URL + '/api/v1/flows/external-grants/' + encodeURIComponent(req.params.grant_id) + q,
886	req,
887	res,
888	);
889	});
890
891	// Phase 18: image upload — gateway buffers the file, fetches GitHub token from bridge,
892	// then commits directly to GitHub (avoids forwarding a multipart body to another Lambda).
893	app.post(/^\/api\/v1\/notes\/(.+)\/upload-image$/, async (req, res) => {
894	const uid = getUserId(req);
895	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
896
897	// 1. Get GitHub connection (token + repo) from bridge.
898	let ghToken, ghRepo;
899	try {
900	const tokenRes = await fetch(`${BRIDGE_URL}/api/v1/vault/github-token`, {
901	headers: { authorization: req.headers.authorization \|\| '' },
902	});
903	if (!tokenRes.ok) {
904	const errData = await tokenRes.json().catch(() => ({}));
905	return res.status(tokenRes.status).json({
906	error: errData.error \|\| 'GitHub not connected',
907	code: errData.code \|\| 'GITHUB_NOT_CONNECTED',
908	});
909	}
910	const data = await tokenRes.json();
911	ghToken = data.token;
912	ghRepo = data.repo;
913	} catch (e) {
914	return res.status(502).json({ error: 'Could not reach bridge', code: 'BAD_GATEWAY' });
915	}
916	if (!ghToken) return res.status(400).json({ error: 'GitHub not connected', code: 'GITHUB_NOT_CONNECTED' });
917	if (!ghRepo) return res.status(400).json({ error: 'GitHub repo not set. Back up once first to set the remote.', code: 'GITHUB_NOT_CONFIGURED' });
918
919	// 2. Buffer the uploaded file from the multipart body.
920	let fileBuffer, originalName, mimeType;
921	try {
922	const raw = await bufferImportRequestBody(req);
923	const ct = req.headers['content-type'] \|\| '';
924	const boundaryMatch = ct.match(/boundary=([^\s;]+)/i);
925	if (!boundaryMatch) return res.status(400).json({ error: 'Content-Type boundary missing', code: 'BAD_REQUEST' });
926	const boundary = boundaryMatch[1];
927	// Parse the first file part from the multipart body manually (avoids multer dependency).
928	const parsed = parseMultipartFile(raw, boundary);
929	if (!parsed) return res.status(400).json({ error: 'image file required', code: 'BAD_REQUEST' });
930	fileBuffer = parsed.data;
931	originalName = parsed.filename \|\| 'image.jpg';
932	mimeType = parsed.contentType \|\| 'application/octet-stream';
933	} catch (e) {
934	return res.status(500).json({ error: 'Could not read upload body', code: 'INTERNAL_ERROR' });
935	}
936
937	// 3. Validate extension, content-type, and magic bytes.
938	try { validateImageExtension(originalName); } catch (e) {
939	return res.status(400).json({ error: e.message, code: 'BAD_REQUEST' });
940	}
941	if (!mimeType.toLowerCase().startsWith('image/')) {
942	return res.status(400).json({ error: 'File content-type must be image/*', code: 'BAD_REQUEST' });
943	}
944	const ext = originalName.split('.').pop().toLowerCase();
945	const magicOk = validateMagicBytes(fileBuffer, ext);
946	if (!magicOk) {
947	return res.status(400).json({ error: 'File content does not match declared image type', code: 'BAD_REQUEST' });
948	}
949
950	// 4. Commit to GitHub directly from the gateway.
951	try {
952	const now = new Date();
953	const yearMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
954	const safeName = originalName.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 128);
955	const uniqueName = `${Date.now()}-${safeName}`;
956	const repoFilePath = `media/images/${yearMonth}/${uniqueName}`;
957	const result = await commitImageToRepo({
958	accessToken: ghToken,
959	repoUrl: ghRepo,
960	filePath: repoFilePath,
961	fileBuffer,
962	commitMessage: `Add image: ${safeName}`,
963	});
964	return res.json({
965	url: result.url,
966	inserted_markdown: `![${safeName}](${result.url})`,
967	sha: result.sha,
968	repo_path: repoFilePath,
969	repo_private: result.isPrivate === true,
970	});
971	} catch (e) {
972	const msg = e.message \|\| String(e);
973	const clientErr = /not found\|not connected\|lacks permission\|lacks repo\|Reconnect\|scope\|remote/i.test(msg);
974	return res.status(clientErr ? 400 : 500).json({ error: msg, code: clientErr ? 'BAD_REQUEST' : 'RUNTIME_ERROR' });
975	}
976	});
977
978	app.get('/api/v1/vault/image-proxy-token', (req, res) => {
979	const uid = getUserId(req);
980	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
981	if (!SESSION_SECRET) return res.status(503).json({ error: 'Not configured', code: 'NOT_CONFIGURED' });
982	const token = signImageProxyToken(SESSION_SECRET, uid);
983	res.json({ token, expires_in: IMAGE_PROXY_TOKEN_TTL_SECONDS });
984	});
985
986	app.get('/api/v1/vault/image-proxy', async (req, res) => {
987	const auth = req.headers.authorization \|\| '';
988	const headerToken = auth.startsWith('Bearer ') ? auth.slice(7) : null;
989	const queryToken = typeof req.query.token === 'string' ? req.query.token : null;
990	let uid = headerToken ? getUserId({ headers: { authorization: `Bearer ${headerToken}` } }) : null;
991	let jwtTokenForBridge = headerToken \|\| '';
992	if (!uid && queryToken && SESSION_SECRET) {
993	uid = verifyImageProxyToken(SESSION_SECRET, queryToken);
994	}
995	// Backward compat: old hub.js sends full JWT as ?token= (pre-signed-token change).
996	if (!uid && queryToken) {
997	const fromJwt = getUserId({ headers: { authorization: `Bearer ${queryToken}` } });
998	if (fromJwt) { uid = fromJwt; jwtTokenForBridge = queryToken; }
999	}
1000	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
1001
1002	// When uid is known but no JWT to forward (HMAC token auth path), mint a
1003	// short-lived gateway JWT so the bridge can identify the user.
1004	if (!jwtTokenForBridge && SESSION_SECRET) {
1005	try { jwtTokenForBridge = jwt.sign({ sub: uid }, SESSION_SECRET, { expiresIn: '5m' }); } catch (_) {}
1006	}
1007
1008	const rawUrl = typeof req.query.url === 'string' ? req.query.url : '';
1009	if (!rawUrl) return res.status(400).json({ error: 'url parameter required', code: 'BAD_REQUEST' });
1010
1011	// Only proxy raw.githubusercontent.com URLs to prevent SSRF.
1012	const rawMatch = rawUrl.match(
1013	/^https:\/\/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)$/i,
1014	);
1015	if (!rawMatch) {
1016	return res.status(400).json({ error: 'Only raw.githubusercontent.com URLs are supported', code: 'BAD_REQUEST' });
1017	}
1018	const [, owner, repo, ref, filePath] = rawMatch;
1019
1020	let ghToken = null;
1021	if (jwtTokenForBridge) {
1022	try {
1023	const tokenRes = await fetch(`${BRIDGE_URL}/api/v1/vault/github-token`, {
1024	headers: { authorization: `Bearer ${jwtTokenForBridge}` },
1025	});
1026	if (tokenRes.ok) {
1027	const data = await tokenRes.json();
1028	ghToken = data.token \|\| null;
1029	}
1030	} catch (_) { /* bridge unreachable — fall through, public repos still work */ }
1031	}
1032
1033	if (!ghToken) {
1034	// No stored GitHub token — assume the repo is public and redirect directly.
1035	return res.redirect(302, rawUrl);
1036	}
1037
1038	// Use the GitHub Contents API to get a signed, short-lived download_url for the file.
1039	// This avoids sending the PAT in the redirect URL while still letting private-repo images load.
1040	const apiUrl =
1041	`https://api.github.com/repos/${owner}/${repo}/contents/${filePath}` +
1042	`?ref=${encodeURIComponent(ref)}`;
1043	try {
1044	const apiRes = await fetch(apiUrl, {
1045	headers: {
1046	Authorization: `token ${ghToken}`,
1047	Accept: 'application/vnd.github.v3+json',
1048	'User-Agent': 'Knowtation-Hub/1.0',
1049	},
1050	});
1051	if (apiRes.ok) {
1052	const data = await apiRes.json();
1053	const dlUrl = data.download_url \|\| rawUrl;
1054	res.setHeader('Cache-Control', 'private, max-age=300');
1055	return res.redirect(302, dlUrl);
1056	}
1057	// GitHub returned an error (e.g. 404 file missing, 403 large-file).
1058	const errBody = await apiRes.json().catch(() => ({}));
1059	return res.status(apiRes.status).json({
1060	error: errBody.message \|\| 'Image not found on GitHub',
1061	code: 'UPSTREAM_ERROR',
1062	});
1063	} catch (e) {
1064	return res.status(502).json({ error: 'Failed to fetch image metadata from GitHub', code: 'BAD_GATEWAY' });
1065	}
1066	});
1067	}
1068
1069	/**
1070	* Safe client request headers that may be forwarded to upstream services.
1071	* Using an explicit allowlist prevents host-header injection, internal proxy header leakage,
1072	* and forwarding of security-sensitive headers (cookies, x-forwarded-for, etc.) to upstreams.
1073	*/
1074	const PROXY_HEADER_ALLOWLIST = new Set([
1075	'content-type',
1076	'accept',
1077	'accept-language',
1078	'accept-encoding',
1079	]);
1080
1081	/**
1082	* Incoming headers describe the client body. We often re-serialize JSON (provenance merge), so
1083	* length and transfer-related headers must not be forwarded: Undici can hang or mis-send if
1084	* Content-Length still matches the old, shorter body.
1085	*/
1086	function stripStaleOutboundBodyHeaders(headers) {
1087	for (const k of Object.keys(headers)) {
1088	const l = k.toLowerCase();
1089	if (
1090	l === 'content-length' \|\|
1091	l === 'transfer-encoding' \|\|
1092	l === 'content-encoding'
1093	) {
1094	delete headers[k];
1095	}
1096	}
1097	}
1098
1099	async function proxyTo(baseUrl, url, req, res) {
1100	const headers = { host: new URL(baseUrl).host };
1101	// Allowlist: only forward safe headers; also forward authorization for bridge JWT auth
1102	// and x-vault-id for vault routing. Never forward origin, referer, cookies, or proxy headers.
1103	for (const k of PROXY_HEADER_ALLOWLIST) {
1104	if (req.headers[k] !== undefined) headers[k] = req.headers[k];
1105	}
1106	if (req.headers.authorization) headers.authorization = req.headers.authorization;
1107	if (req.headers['x-vault-id']) headers['x-vault-id'] = req.headers['x-vault-id'];
1108	const opts = { method: req.method, headers };
1109	if (req.method !== 'GET' && req.method !== 'HEAD' && req.body !== undefined) {
1110	opts.body = typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
1111	stripStaleOutboundBodyHeaders(headers);
1112	}
1113	try {
1114	const upstream = await fetch(url, opts);
1115	const body = await upstream.text();
1116	const hop = filterUpstreamResponseHeadersForDecodedBody(upstream.headers.entries());
1117	res.status(upstream.status).set(Object.fromEntries(hop));
1118	res.send(body);
1119	} catch (e) {
1120	console.error('Gateway proxy (bridge) error:', e.message);
1121	res.status(502).json({ error: 'Bad Gateway', code: 'BAD_GATEWAY' });
1122	}
1123	}
1124
1125	/**
1126	* Read multipart/raw POST body for import proxy.
1127	* Netlify (serverless-http) attaches the Lambda body as Buffer on `req.body` and uses a synthetic stream;
1128	* `fetch(req, { duplex })` is unreliable there — always buffer then POST bytes.
1129	* @param {import('express').Request} req
1130	* @returns {Promise<Buffer>}
1131	*/
1132	async function bufferImportRequestBody(req) {
1133	if (Buffer.isBuffer(req.body)) return req.body;
1134	if (req.body instanceof Uint8Array) return Buffer.from(req.body);
1135	if (typeof req.body === 'string') return Buffer.from(req.body, 'latin1');
1136	const chunks = [];
1137	for await (const chunk of req) {
1138	chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
1139	}
1140	return Buffer.concat(chunks);
1141	}
1142
1143
1144	/**
1145	* Multipart import: forward body bytes to bridge (do not use proxyTo — body is not JSON in req.body).
1146	* @param {string} _baseUrl - bridge origin (reserved for diagnostics; fetch URL is `url`)
1147	* @param {string} url - full URL to bridge /api/v1/import
1148	* @param {import('express').Request} req
1149	* @param {import('express').Response} res
1150	*/
1151	async function proxyImportToBridge(_baseUrl, url, req, res) {
1152	let raw;
1153	try {
1154	raw = await bufferImportRequestBody(req);
1155	} catch (e) {
1156	console.error('Gateway import proxy (read body):', e.message \|\| e);
1157	return res.status(500).json({ error: 'Could not read upload body', code: 'INTERNAL_ERROR' });
1158	}
1159	if (!raw.length) {
1160	return res.status(400).json({ error: 'Empty upload body', code: 'BAD_REQUEST' });
1161	}
1162	// Do not set `Host` manually — undici derives it from the request URL; a wrong Host breaks some upstreams.
1163	const headers = {
1164	authorization: req.headers.authorization \|\| '',
1165	'x-vault-id': String(req.headers['x-vault-id'] \|\| 'default'),
1166	};
1167	const ct = req.headers['content-type'];
1168	if (ct) headers['content-type'] = ct;
1169	headers['content-length'] = String(raw.length);
1170	let upstream;
1171	try {
1172	upstream = await fetch(url, {
1173	method: 'POST',
1174	headers,
1175	body: raw,
1176	});
1177	} catch (e) {
1178	console.error('Gateway import proxy error:', e.message, e.cause);
1179	const detail = e.cause?.message \|\| e.message \|\| String(e);
1180	return res.status(502).json({
1181	error: 'Bad Gateway',
1182	code: 'BAD_GATEWAY',
1183	detail,
1184	});
1185	}
1186	const body = await upstream.text();
1187	const upstreamCt = upstream.headers.get('content-type') \|\| '';
1188	if (
1189	upstream.status >= 400 &&
1190	!/application\/json/i.test(upstreamCt) &&
1191	body.trimStart().startsWith('<')
1192	) {
1193	return res.status(upstream.status).json({
1194	error: 'Import service returned a non-JSON error (check bridge Netlify function logs).',
1195	code: 'BAD_GATEWAY',
1196	detail: `HTTP ${upstream.status}`,
1197	});
1198	}
1199	const hop = filterUpstreamResponseHeadersForDecodedBody(upstream.headers.entries());
1200	res.status(upstream.status).set(Object.fromEntries(hop));
1201	res.send(body);
1202	}
1203
1204	// Proxy /api/* to canister with X-User-Id from JWT
1205	function getUserId(req) {
1206	const auth = req.headers.authorization;
1207	const token = auth && auth.startsWith('Bearer ') ? auth.slice(7) : null;
1208	return token ? verifyToken(token) : null;
1209	}
1210
1211	/**
1212	* Validate a hosted SectionSource note path before any upstream fetch.
1213	* @param {unknown} rawPath
1214	* @returns {string}
1215	*/
1216	function normalizeGatewaySectionSourcePath(rawPath) {
1217	if (typeof rawPath !== 'string' \|\| rawPath.trim() === '') {
1218	throw new Error('Invalid path');
1219	}
1220	const forward = rawPath.trim().replace(/\\/g, '/');
1221	if (forward.startsWith('/') \|\| /^[A-Za-z]:\//.test(forward)) {
1222	throw new Error('Invalid path');
1223	}
1224	const parts = forward.split('/').filter(Boolean);
1225	if (parts.includes('..')) {
1226	throw new Error('Invalid path');
1227	}
1228	return parts.join('/');
1229	}
1230
1231	/**
1232	* Validate a hosted NoteOutline note path before any upstream fetch.
1233	* @param {unknown} rawPath
1234	* @returns {string}
1235	*/
1236	function normalizeGatewayNoteOutlinePath(rawPath) {
1237	return normalizeGatewaySectionSourcePath(rawPath);
1238	}
1239
1240	/**
1241	* Validate a hosted DocumentTree note path before any upstream fetch.
1242	* @param {unknown} rawPath
1243	* @returns {string}
1244	*/
1245	function normalizeGatewayDocumentTreePath(rawPath) {
1246	return normalizeGatewaySectionSourcePath(rawPath);
1247	}
1248
1249	/**
1250	* Validate a hosted MetadataFacets note path before any upstream fetch.
1251	* @param {unknown} rawPath
1252	* @returns {string}
1253	*/
1254	function normalizeGatewayMetadataFacetsPath(rawPath) {
1255	return normalizeGatewaySectionSourcePath(rawPath);
1256	}
1257
1258	/**
1259	* @param {unknown} error
1260	*/
1261	function sanitizedSectionSourceGatewayError(error) {
1262	const msg = error?.message \|\| String(error ?? '');
1263	if (/^Invalid path\b/.test(msg)) return { status: 400, error: 'Invalid path', code: 'INVALID_PATH' };
1264	return { status: 502, error: 'Bad Gateway', code: 'BAD_GATEWAY' };
1265	}
1266
1267	/**
1268	* @param {unknown} error
1269	*/
1270	function sanitizedNoteOutlineGatewayError(error) {
1271	return sanitizedSectionSourceGatewayError(error);
1272	}
1273
1274	/**
1275	* @param {unknown} error
1276	*/
1277	function sanitizedDocumentTreeGatewayError(error) {
1278	return sanitizedSectionSourceGatewayError(error);
1279	}
1280
1281	/**
1282	* @param {unknown} error
1283	*/
1284	function sanitizedMetadataFacetsGatewayError(error) {
1285	return sanitizedSectionSourceGatewayError(error);
1286	}
1287
1288	const hostedCtxCache = new Map();
1289	const HOSTED_CTX_TTL_MS = 60_000;
1290	const HOSTED_CONTEXT_FETCH_TIMEOUT_MS = (() => {
1291	const n = parseInt(String(process.env.HOSTED_CONTEXT_FETCH_TIMEOUT_MS \|\| ''), 10);
1292	if (!Number.isFinite(n)) return 3000;
1293	return Math.min(10_000, Math.max(250, n));
1294	})();
1295
1296	function hostedContextAbortSignal() {
1297	return typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
1298	? AbortSignal.timeout(HOSTED_CONTEXT_FETCH_TIMEOUT_MS)
1299	: undefined;
1300	}
1301
1302	/**
1303	* Bridge-hosted team context (vault allowlist + scope + effective canister user). Cached briefly per (sub, vaultId).
1304	* @param {import('express').Request} req
1305	* @returns {Promise<Record<string, unknown>\|null>}
1306	*/
1307	async function getHostedAccessContext(req) {
1308	if (!BRIDGE_URL) return null;
1309	const auth = req.headers.authorization;
1310	if (!auth \|\| !auth.startsWith('Bearer ')) return null;
1311	const sub = getUserId(req);
1312	if (!sub) return null;
1313	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
1314	const cacheKey = `${sub}\0${vaultId}`;
1315	const now = Date.now();
1316	const hit = hostedCtxCache.get(cacheKey);
1317	if (hit && hit.expires > now) return hit.data;
1318	try {
1319	const signal = hostedContextAbortSignal();
1320	const r = await fetch(BRIDGE_URL + '/api/v1/hosted-context', {
1321	method: 'GET',
1322	headers: {
1323	Authorization: auth,
1324	Accept: 'application/json',
1325	'X-Vault-Id': vaultId,
1326	},
1327	...(signal ? { signal } : {}),
1328	});
1329	if (!r.ok) return null;
1330	const data = await r.json();
1331	if (data && data.error && !data.effective_canister_user_id) return null;
1332	hostedCtxCache.set(cacheKey, { expires: now + HOSTED_CTX_TTL_MS, data });
1333	return data;
1334	} catch (_) {
1335	return null;
1336	}
1337	}
1338
1339	/**
1340	* Hosted team context for an explicit vault (e.g. cross-vault copy source/target checks).
1341	* @param {string} authorization Bearer JWT
1342	* @param {string} vaultId
1343	* @returns {Promise<Record<string, unknown>\|null>}
1344	*/
1345	async function fetchHostedAccessContextForVault(authorization, vaultId) {
1346	if (!BRIDGE_URL \|\| !authorization \|\| !authorization.startsWith('Bearer ')) return null;
1347	const token = authorization.slice(7);
1348	const sub = verifyToken(token);
1349	if (!sub) return null;
1350	const vid = String(vaultId \|\| 'default').trim() \|\| 'default';
1351	const cacheKey = `${sub}\0${vid}`;
1352	const now = Date.now();
1353	const hit = hostedCtxCache.get(cacheKey);
1354	if (hit && hit.expires > now) return hit.data;
1355	try {
1356	const signal = hostedContextAbortSignal();
1357	const r = await fetch(BRIDGE_URL + '/api/v1/hosted-context', {
1358	method: 'GET',
1359	headers: {
1360	Authorization: authorization,
1361	Accept: 'application/json',
1362	'X-Vault-Id': vid,
1363	},
1364	...(signal ? { signal } : {}),
1365	});
1366	if (!r.ok) return null;
1367	const data = await r.json();
1368	if (data && data.error && !data.effective_canister_user_id) return null;
1369	hostedCtxCache.set(cacheKey, { expires: now + HOSTED_CTX_TTL_MS, data });
1370	return data;
1371	} catch (_) {
1372	return null;
1373	}
1374	}
1375
1376	const metadataBulkHandlers = createMetadataBulkHandlers({
1377	CANISTER_URL,
1378	CANISTER_AUTH_SECRET,
1379	BRIDGE_URL,
1380	SESSION_SECRET: SESSION_SECRET \|\| '',
1381	getUserId,
1382	getHostedAccessContext,
1383	});
1384
1385	app.get('/api/v1/billing/summary', (req, res) => handleBillingSummary(req, res, getUserId));
1386
1387	/**
1388	* POST /api/v1/admin/billing/repair
1389	*
1390	* Admin-only endpoint to directly write billing tier and Stripe linkage fields for a user.
1391	* Used to recover from missed or unprocessable Stripe webhook deliveries (e.g. webhook pointed
1392	* at old URL, checkout session never had user_id metadata, billing DB was empty on a new deploy).
1393	*
1394	* Auth: Bearer JWT with admin role (sub must be in HUB_ADMIN_USER_IDS env var).
1395	* Body: { uid?, tier, stripe_subscription_id?, stripe_customer_id?, has_active_subscription? }
1396	* - uid: target Knowtation user ID (defaults to the calling admin's own uid)
1397	* - tier: required — one of: free \| beta \| plus \| growth \| pro \| starter \| team
1398	* - stripe_subscription_id: if provided (non-null), also sets has_active_subscription = true
1399	* - has_active_subscription: optional boolean override; when omitted, defaults to true
1400	* whenever a non-null stripe_subscription_id is supplied, and no-op otherwise
1401	* - stripe_customer_id: if provided, links the user to their Stripe customer so future
1402	* webhook events (subscription.updated, etc.) can find them
1403	*
1404	* All mutations are logged. This endpoint does NOT create a Stripe subscription — it only
1405	* repairs the local billing DB record.
1406	*/
1407	const VALID_REPAIR_TIERS = new Set(['free', 'beta', 'plus', 'growth', 'pro', 'starter', 'team']);
1408
1409	app.post('/api/v1/admin/billing/repair', async (req, res) => {
1410	const callerUid = getUserId(req);
1411	if (!callerUid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
1412	if (roleForSub(callerUid) !== 'admin') return res.status(403).json({ error: 'Forbidden', code: 'FORBIDDEN' });
1413
1414	const body = req.body && typeof req.body === 'object' ? req.body : {};
1415	const targetUid = typeof body.uid === 'string' && body.uid.trim() ? body.uid.trim() : callerUid;
1416	const tier = typeof body.tier === 'string' ? body.tier.trim() : '';
1417
1418	if (!VALID_REPAIR_TIERS.has(tier)) {
1419	return res.status(400).json({
1420	error: 'Invalid or missing tier',
1421	code: 'BAD_REQUEST',
1422	valid_tiers: [...VALID_REPAIR_TIERS],
1423	});
1424	}
1425
1426	const stripeSubId =
1427	typeof body.stripe_subscription_id === 'string' ? body.stripe_subscription_id.trim() \|\| null : undefined;
1428	const stripeCustomerId =
1429	typeof body.stripe_customer_id === 'string' ? body.stripe_customer_id.trim() \|\| null : undefined;
1430	// Explicit override: caller may pass has_active_subscription=false to deactivate.
1431	// When stripe_subscription_id is provided: truthy value → true, null (cleared) → false.
1432	// When stripe_subscription_id is omitted entirely: no-op (undefined).
1433	const hasActiveSub =
1434	typeof body.has_active_subscription === 'boolean'
1435	? body.has_active_subscription
1436	: stripeSubId !== undefined
1437	? (stripeSubId !== null)
1438	: undefined;
1439
1440	let before;
1441	try {
1442	await mutateBillingDb((db) => {
1443	if (!db.users[targetUid]) db.users[targetUid] = defaultUserRecord(targetUid);
1444	const u = db.users[targetUid];
1445	before = {
1446	tier: u.tier,
1447	has_active_subscription: u.has_active_subscription,
1448	stripe_subscription_id: u.stripe_subscription_id,
1449	stripe_customer_id: u.stripe_customer_id,
1450	};
1451	u.tier = tier;
1452	if (MONTHLY_INCLUDED_CENTS_BY_TIER[tier] !== undefined) {
1453	u.monthly_included_cents = MONTHLY_INCLUDED_CENTS_BY_TIER[tier];
1454	}
1455	if (stripeSubId !== undefined) u.stripe_subscription_id = stripeSubId;
1456	if (stripeCustomerId !== undefined) u.stripe_customer_id = stripeCustomerId;
1457	if (hasActiveSub !== undefined) u.has_active_subscription = hasActiveSub;
1458	});
1459	} catch (e) {
1460	console.error('[admin/billing/repair] mutateBillingDb failed:', e?.message);
1461	return res.status(500).json({ error: 'Internal Server Error', code: 'INTERNAL' });
1462	}
1463
1464	console.log(
1465	`[admin/billing/repair] caller=${callerUid} target=${targetUid}` +
1466	` tier: ${before?.tier} → ${tier}` +
1467	(hasActiveSub !== undefined ? ` has_active_subscription: ${before?.has_active_subscription} → ${hasActiveSub}` : '') +
1468	(stripeSubId !== undefined ? ` sub: ${before?.stripe_subscription_id} → ${stripeSubId}` : '') +
1469	(stripeCustomerId !== undefined ? ` cus: ${before?.stripe_customer_id} → ${stripeCustomerId}` : ''),
1470	);
1471
1472	return res.json({
1473	ok: true,
1474	uid: targetUid,
1475	tier,
1476	has_active_subscription: hasActiveSub !== undefined ? hasActiveSub : '(unchanged)',
1477	stripe_subscription_id: stripeSubId !== undefined ? stripeSubId : '(unchanged)',
1478	stripe_customer_id: stripeCustomerId !== undefined ? stripeCustomerId : '(unchanged)',
1479	before,
1480	});
1481	});
1482
1483	/**
1484	* POST /api/v1/billing/checkout
1485	* Body: { price_id, success_url, cancel_url } OR { tier, success_url, cancel_url }
1486	* Returns: { url } — Stripe Checkout Session URL.
1487	* mode is automatically determined: subscription for tiers, payment for token packs.
1488	*/
1489	app.post('/api/v1/billing/checkout', async (req, res) => {
1490	const uid = getUserId(req);
1491	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
1492
1493	const body = req.body && typeof req.body === 'object' ? req.body : {};
1494	let priceId = typeof body.price_id === 'string' ? body.price_id.trim() : null;
1495
1496	if (!priceId && typeof body.tier === 'string') {
1497	priceId = priceIdFromTierShorthand(body.tier.trim());
1498	if (!priceId) {
1499	return res.status(400).json({
1500	error: `Unknown tier '${body.tier}' or Stripe price env var not configured.`,
1501	code: 'BAD_REQUEST',
1502	});
1503	}
1504	}
1505
1506	if (!priceId && typeof body.pack_size === 'string') {
1507	const packSizeMap = {
1508	small: process.env.STRIPE_PRICE_PACK_10 \|\| null,
1509	medium: process.env.STRIPE_PRICE_PACK_25 \|\| null,
1510	large: process.env.STRIPE_PRICE_PACK_50 \|\| null,
1511	};
1512	priceId = packSizeMap[body.pack_size.toLowerCase()] \|\| null;
1513	if (!priceId) {
1514	return res.status(400).json({
1515	error: `Unknown pack_size '${body.pack_size}' or Stripe pack price env var not configured.`,
1516	code: 'BAD_REQUEST',
1517	});
1518	}
1519	}
1520
1521	if (!priceId) {
1522	return res.status(400).json({ error: 'price_id, tier, or pack_size is required', code: 'BAD_REQUEST' });
1523	}
1524
1525	const isSub = isSubscriptionPriceId(priceId);
1526	const isPack = isPackPriceId(priceId);
1527
1528	if (!isSub && !isPack) {
1529	return res.status(400).json({
1530	error: 'price_id is not a recognised Knowtation subscription or token pack price.',
1531	code: 'BAD_REQUEST',
1532	});
1533	}
1534
1535	const mode = isSub ? 'subscription' : 'payment';
1536
1537	const rawSuccessUrl = typeof body.success_url === 'string' ? body.success_url.trim() : '';
1538	const rawCancelUrl = typeof body.cancel_url === 'string' ? body.cancel_url.trim() : '';
1539
1540	const fallbackBase = HUB_UI_ORIGIN \|\| BASE_URL;
1541	const successUrl = rawSuccessUrl \|\| `${fallbackBase}/hub/#settings`;
1542	const cancelUrl = rawCancelUrl \|\| `${fallbackBase}/hub/#settings`;
1543
1544	try {
1545	const { url } = await createCheckoutSession({
1546	priceId,
1547	userId: uid,
1548	successUrl,
1549	cancelUrl,
1550	mode,
1551	stripeCustomerId: null,
1552	});
1553	return res.json({ url });
1554	} catch (e) {
1555	const code = e.code \|\| 'STRIPE_ERROR';
1556	if (code === 'NOT_CONFIGURED') {
1557	return res.status(503).json({ error: e.message, code });
1558	}
1559	console.error('[billing/checkout] Stripe error:', e.message);
1560	return res.status(502).json({ error: e.message \|\| 'Stripe checkout failed', code });
1561	}
1562	});
1563
1564	/**
1565	* POST /api/v1/billing/portal
1566	* Body: { return_url? }
1567	* Returns: { url } — Stripe Billing Portal session URL.
1568	*/
1569	app.post('/api/v1/billing/portal', async (req, res) => {
1570	const uid = getUserId(req);
1571	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
1572
1573	const body = req.body && typeof req.body === 'object' ? req.body : {};
1574	const rawReturnUrl = typeof body.return_url === 'string' ? body.return_url.trim() : '';
1575	const fallbackBase = HUB_UI_ORIGIN \|\| BASE_URL;
1576	const returnUrl = rawReturnUrl \|\| `${fallbackBase}/hub/#settings`;
1577
1578	try {
1579	const { url } = await createPortalSession({ userId: uid, returnUrl });
1580	return res.json({ url });
1581	} catch (e) {
1582	const code = e.code \|\| 'STRIPE_ERROR';
1583	if (code === 'NOT_CONFIGURED') {
1584	return res.status(503).json({ error: e.message, code });
1585	}
1586	console.error('[billing/portal] Stripe error:', e.message);
1587	return res.status(502).json({ error: e.message \|\| 'Stripe portal failed', code });
1588	}
1589	});
1590
1591	// GET /api/v1/settings and GET /api/v1/setup — hosted: vault_list from canister; bridge fields when BRIDGE_URL set
1592	app.get('/api/v1/settings', async (req, res) => {
1593	const uid = getUserId(req);
1594	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
1595	let vault_list = [{ id: 'default', label: 'Default' }];
1596	let allowed_vault_ids = ['default'];
1597	let canisterVaultUserId = uid;
1598	/** @type {string\|null} */
1599	let workspace_owner_id = null;
1600	let hosted_delegating = false;
1601	/** @type {string[]\|null} */
1602	let allowedFromBridge = null;
1603	if (BRIDGE_URL && req.headers.authorization) {
1604	try {
1605	const signal = hostedContextAbortSignal();
1606	const hRes = await fetch(BRIDGE_URL + '/api/v1/hosted-context/settings', {
1607	method: 'GET',
1608	headers: {
1609	Authorization: req.headers.authorization,
1610	Accept: 'application/json',
1611	},
1612	...(signal ? { signal } : {}),
1613	});
1614	if (hRes.ok) {
1615	const hc = await hRes.json();
1616	if (hc.effective_canister_user_id && typeof hc.effective_canister_user_id === 'string') {
1617	canisterVaultUserId = hc.effective_canister_user_id;
1618	}
1619	if (Array.isArray(hc.allowed_vault_ids) && hc.allowed_vault_ids.length > 0) {
1620	allowedFromBridge = hc.allowed_vault_ids.map((x) => String(x));
1621	}
1622	if (hc.workspace_owner_id != null && String(hc.workspace_owner_id).trim() !== '') {
1623	workspace_owner_id = String(hc.workspace_owner_id).trim();
1624	}
1625	if (hc.delegating === true) hosted_delegating = true;
1626	} else if (hRes.status === 403) {
1627	allowedFromBridge = [];
1628	}
1629	} catch (_) {
1630	/* use uid-only fallback */
1631	}
1632	}
1633	if (CANISTER_URL) {
1634	try {
1635	const signal = hostedContextAbortSignal();
1636	const vRes = await fetch(CANISTER_URL + '/api/v1/vaults', {
1637	method: 'GET',
1638	headers: { 'X-User-Id': canisterVaultUserId, Accept: 'application/json', ...canisterAuthHeaders() },
1639	...(signal ? { signal } : {}),
1640	});
1641	if (vRes.ok) {
1642	const data = await vRes.json();
1643	const vaults = Array.isArray(data.vaults) ? data.vaults : [];
1644	if (vaults.length > 0) {
1645	const mapped = vaults.map((v) => ({
1646	id: String(v.id \|\| 'default'),
1647	label: String(v.label != null && v.label !== '' ? v.label : v.id \|\| 'default'),
1648	}));
1649	if (allowedFromBridge !== null) {
1650	allowed_vault_ids = allowedFromBridge.filter((id) => mapped.some((m) => m.id === id));
1651	vault_list = allowed_vault_ids.map((id) => {
1652	const m = mapped.find((x) => x.id === id);
1653	return m \|\| { id, label: id };
1654	});
1655	} else {
1656	vault_list = mapped;
1657	allowed_vault_ids = vault_list.map((v) => v.id);
1658	}
1659	} else if (allowedFromBridge && allowedFromBridge.length > 0) {
1660	allowed_vault_ids = [...allowedFromBridge];
1661	vault_list = allowedFromBridge.map((id) => ({ id, label: id }));
1662	}
1663	} else {
1664	console.warn('[gateway] canister vaults non-ok', vRes.status);
1665	}
1666	} catch (e) {
1667	console.warn('[gateway] canister vaults unreachable', e?.message \|\| String(e));
1668	}
1669	}
1670	let github_connected = false;
1671	let github_repo = null;
1672	let role = roleForSub(uid);
1673	let hub_evaluator_may_approve = process.env.HUB_EVALUATOR_MAY_APPROVE === '1';
1674	if (BRIDGE_URL && req.headers.authorization) {
1675	try {
1676	const ghRes = await fetch(BRIDGE_URL + '/api/v1/vault/github-status', {
1677	method: 'GET',
1678	headers: { Authorization: req.headers.authorization, Accept: 'application/json' },
1679	});
1680	if (ghRes.ok) {
1681	const data = await ghRes.json();
1682	github_connected = Boolean(data.github_connected);
1683	github_repo = data.repo \|\| null;
1684	} else {
1685	console.warn('[gateway] bridge github-status non-ok', ghRes.status);
1686	}
1687	const roleRes = await fetch(BRIDGE_URL + '/api/v1/role', {
1688	method: 'GET',
1689	headers: { Authorization: req.headers.authorization, Accept: 'application/json' },
1690	});
1691	if (roleRes.ok) {
1692	const data = await roleRes.json();
1693	if (data.role) role = data.role;
1694	if (typeof data.may_approve_proposals === 'boolean') hub_evaluator_may_approve = data.may_approve_proposals;
1695	}
1696	} catch (e) {
1697	console.warn('[gateway] bridge unreachable', e?.message \|\| String(e));
1698	}
1699	}
1700	const vault_git = {
1701	enabled: github_connected,
1702	has_remote: Boolean(github_repo),
1703	auto_commit: false,
1704	auto_push: false,
1705	};
1706	const dataDir = path.join(projectRoot, 'data');
1707	const llmPrefs = await loadHostedProposalLlmPrefs();
1708	res.json({
1709	role,
1710	user_id: uid,
1711	vault_id: 'default',
1712	vault_list,
1713	allowed_vault_ids,
1714	vault_path_display: 'Canister',
1715	vault_git,
1716	github_connect_available: Boolean(BRIDGE_URL),
1717	github_connected,
1718	repo: github_repo,
1719	workspace_owner_id,
1720	hosted_delegating,
1721	embedding_display: { provider: '—', model: '—', ollama_url: '—' },
1722	proposal_enrich_enabled: effectiveHostedEnrich(llmPrefs),
1723	proposal_evaluation_required: effectiveHostedEvaluationRequired(llmPrefs, dataDir),
1724	proposal_review_hints_enabled: effectiveHostedReviewHints(llmPrefs),
1725	proposal_policy_stored: {
1726	proposal_evaluation_required: llmPrefs.proposal_evaluation_required,
1727	review_hints_enabled: llmPrefs.review_hints_enabled,
1728	enrich_enabled: llmPrefs.enrich_enabled,
1729	},
1730	proposal_policy_env_locked: proposalPolicyEnvLocked(),
1731	hub_evaluator_may_approve,
1732	proposal_rubric: loadProposalRubric(path.join(projectRoot, 'data')),
1733	daemon: await (async () => {
1734	try {
1735	const db = await loadBillingDb();
1736	const raw = db.users?.[uid] \|\| defaultUserRecord(uid);
1737	const u = normalizeBillingUser(raw);
1738	return {
1739	enabled: false,
1740	interval_minutes: u.consolidation_interval_minutes \|\| 120,
1741	idle_only: true,
1742	idle_threshold_minutes: 15,
1743	run_on_start: false,
1744	max_cost_per_day_usd: null,
1745	passes: u.consolidation_passes,
1746	lookback_hours: u.consolidation_lookback_hours,
1747	max_events_per_pass: u.consolidation_max_events_per_pass,
1748	max_topics_per_pass: u.consolidation_max_topics_per_pass,
1749	llm: {
1750	provider: '',
1751	model: '',
1752	base_url: '',
1753	max_tokens: u.consolidation_llm_max_tokens,
1754	},
1755	hosted_enabled: u.consolidation_enabled,
1756	};
1757	} catch (_) {
1758	return {
1759	enabled: false,
1760	interval_minutes: 120,
1761	idle_only: true,
1762	idle_threshold_minutes: 15,
1763	run_on_start: false,
1764	max_cost_per_day_usd: null,
1765	passes: { consolidate: true, verify: true, discover: false },
1766	lookback_hours: 24,
1767	max_events_per_pass: 200,
1768	max_topics_per_pass: 10,
1769	llm: { provider: '', model: '', base_url: '', max_tokens: 1024 },
1770	hosted_enabled: false,
1771	};
1772	}
1773	})(),
1774	muse_bridge: (() => {
1775	const envOverride = process.env.MUSE_URL != null && String(process.env.MUSE_URL).trim() !== '';
1776	const mc = parseMuseConfigFromEnv();
1777	let origin = null;
1778	if (mc) {
1779	try {
1780	origin = new URL(mc.baseUrl).origin;
1781	} catch (_) {
1782	/* ignore */
1783	}
1784	}
1785	return {
1786	enabled: Boolean(mc),
1787	origin,
1788	source: envOverride ? 'env' : 'none',
1789	env_override_active: envOverride,
1790	url_editable: false,
1791	yaml_url_for_edit: '',
1792	};
1793	})(),
1794	});
1795	});
1796
1797	/** Hosted: Muse base URL is operator env only (not writable from Hub Settings). */
1798	app.post('/api/v1/settings/muse', express.json(), (req, res) => {
1799	res.status(501).json({
1800	error: 'Knowtation Cloud configures the optional Muse link on the server; it cannot be set from this screen.',
1801	code: 'NOT_IMPLEMENTED',
1802	});
1803	});
1804
1805	/**
1806	* POST /api/v1/settings/consolidation
1807	* Hosted mode: save consolidation schedule + pass preferences to the billing store.
1808	* Self-hosted daemon settings are not writable here; respond with an appropriate note.
1809	*/
1810	app.post('/api/v1/settings/consolidation', express.json(), async (req, res) => {
1811	const uid = getUserId(req);
1812	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
1813	const body = req.body && typeof req.body === 'object' ? req.body : {};
1814	const mode = typeof body.mode === 'string' ? body.mode : (body.enabled ? 'daemon' : 'hosted');
1815	const advCheck = validateHostedSettingsConsolidationAdvanced(body);
1816	if (!advCheck.ok) {
1817	return res.status(400).json({ error: advCheck.error, code: advCheck.code });
1818	}
1819	try {
1820	let saved = {};
1821	await mutateBillingDb((db) => {
1822	if (!db.users) db.users = {};
1823	if (!db.users[uid]) db.users[uid] = defaultUserRecord(uid);
1824	const u = normalizeBillingUser(db.users[uid]);
1825	if (mode === 'off') {
1826	u.consolidation_enabled = false;
1827	} else {
1828	u.consolidation_enabled = true;
1829	const iv = Math.floor(Number(body.interval_minutes) \|\| 120);
1830	if (iv >= 1 && iv <= 43200) u.consolidation_interval_minutes = iv;
1831	}
1832	if (body.passes && typeof body.passes === 'object') {
1833	u.consolidation_passes = {
1834	consolidate: body.passes.consolidate !== false,
1835	verify: body.passes.verify !== false,
1836	discover: Boolean(body.passes.discover),
1837	};
1838	}
1839	if (body.lookback_hours !== undefined) {
1840	u.consolidation_lookback_hours = Math.floor(Number(body.lookback_hours));
1841	}
1842	if (body.max_events_per_pass !== undefined) {
1843	u.consolidation_max_events_per_pass = Math.floor(Number(body.max_events_per_pass));
1844	}
1845	if (body.max_topics_per_pass !== undefined) {
1846	u.consolidation_max_topics_per_pass = Math.floor(Number(body.max_topics_per_pass));
1847	}
1848	if (body.llm !== undefined && typeof body.llm === 'object' && body.llm.max_tokens !== undefined) {
1849	u.consolidation_llm_max_tokens = Math.floor(Number(body.llm.max_tokens));
1850	}
1851	normalizeBillingUser(u);
1852	saved = {
1853	hosted_enabled: u.consolidation_enabled,
1854	interval_minutes: u.consolidation_interval_minutes,
1855	passes: u.consolidation_passes,
1856	lookback_hours: u.consolidation_lookback_hours,
1857	max_events_per_pass: u.consolidation_max_events_per_pass,
1858	max_topics_per_pass: u.consolidation_max_topics_per_pass,
1859	llm: {
1860	provider: '',
1861	model: '',
1862	base_url: '',
1863	max_tokens: u.consolidation_llm_max_tokens,
1864	},
1865	};
1866	});
1867	res.json({ ok: true, hosted: true, daemon: { enabled: false, ...saved } });
1868	} catch (e) {
1869	res.status(500).json({ error: e.message \|\| 'Failed to save', code: 'RUNTIME_ERROR' });
1870	}
1871	});
1872
1873	app.post('/api/v1/settings/proposal-policy', requireAdmin, async (req, res) => {
1874	try {
1875	const body = req.body && typeof req.body === 'object' ? req.body : {};
1876	await mergeHostedProposalLlmPrefs({
1877	proposal_evaluation_required: body.proposal_evaluation_required,
1878	review_hints_enabled: body.review_hints_enabled,
1879	enrich_enabled: body.enrich_enabled,
1880	});
1881	res.json({ ok: true });
1882	} catch (e) {
1883	res.status(500).json({ error: e.message, code: 'RUNTIME_ERROR' });
1884	}
1885	});
1886
1887	app.get('/api/v1/setup', (req, res) => {
1888	const uid = getUserId(req);
1889	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
1890	res.json({
1891	vault_path: '',
1892	vault_git: { enabled: false, remote: '' },
1893	});
1894	});
1895
1896	// --- Admin routes: HUB_ADMIN_USER_IDS, or bridge GET /api/v1/role → role "admin" (Team tab) ---
1897	function requireAdmin(req, res, next) {
1898	const uid = getUserId(req);
1899	if (!uid) {
1900	res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
1901	return;
1902	}
1903	if (roleForSub(uid) === 'admin') {
1904	next();
1905	return;
1906	}
1907	if (!BRIDGE_URL \|\| !req.headers.authorization) {
1908	res.status(403).json({ error: 'Admin only', code: 'FORBIDDEN' });
1909	return;
1910	}
1911	void (async () => {
1912	try {
1913	const roleRes = await fetch(BRIDGE_URL + '/api/v1/role', {
1914	method: 'GET',
1915	headers: { Authorization: req.headers.authorization, Accept: 'application/json' },
1916	});
1917	if (!roleRes.ok) {
1918	if (!res.headersSent) res.status(403).json({ error: 'Admin only', code: 'FORBIDDEN' });
1919	return;
1920	}
1921	const data = await roleRes.json();
1922	if (data && data.role === 'admin') {
1923	next();
1924	return;
1925	}
1926	if (!res.headersSent) res.status(403).json({ error: 'Admin only', code: 'FORBIDDEN' });
1927	} catch (e) {
1928	console.warn('[gateway] requireAdmin bridge /role', e?.message \|\| String(e));
1929	if (!res.headersSent) res.status(403).json({ error: 'Admin only', code: 'FORBIDDEN' });
1930	}
1931	})();
1932	}
1933
1934	if (!BRIDGE_URL) {
1935	app.get('/api/v1/workspace', requireAdmin, (_req, res) => {
1936	res.json({ owner_user_id: null });
1937	});
1938	app.post('/api/v1/workspace', requireAdmin, (_req, res) => {
1939	res.status(503).json({ error: 'Workspace owner requires bridge (BRIDGE_URL).', code: 'NOT_AVAILABLE' });
1940	});
1941	app.get('/api/v1/vault-access', requireAdmin, (_req, res) => {
1942	res.json({ access: {} });
1943	});
1944	app.post('/api/v1/vault-access', requireAdmin, (_req, res) => {
1945	res.status(503).json({ error: 'Vault access requires bridge (BRIDGE_URL).', code: 'NOT_AVAILABLE' });
1946	});
1947	app.get('/api/v1/scope', requireAdmin, (_req, res) => {
1948	res.json({ scope: {} });
1949	});
1950	app.post('/api/v1/scope', requireAdmin, (_req, res) => {
1951	res.status(503).json({ error: 'Scope requires bridge (BRIDGE_URL).', code: 'NOT_AVAILABLE' });
1952	});
1953	app.get('/api/v1/hosted-context', (req, res) => {
1954	const uid = getUserId(req);
1955	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
1956	res.status(503).json({ error: 'Hosted context requires bridge (BRIDGE_URL).', code: 'NOT_AVAILABLE' });
1957	});
1958	}
1959
1960	// Hosted: vault list is derived from the canister; YAML vault editor is self-hosted only
1961	app.post('/api/v1/vaults', requireAdmin, (_req, res) => {
1962	res.status(501).json({
1963	error:
1964	'Editing the vault list in Settings is not available on hosted. Vaults appear when you add notes; use the vault switcher or API with X-Vault-Id.',
1965	code: 'NOT_AVAILABLE',
1966	});
1967	});
1968
1969	// GET /api/v1/roles — hosted stub: no role store; admin sees empty list (parity: only admins can open Team)
1970	app.get('/api/v1/roles', requireAdmin, (_req, res) => {
1971	res.json({ roles: [] });
1972	});
1973
1974	// POST /api/v1/roles — no-op on hosted (no persistent role store yet)
1975	app.post('/api/v1/roles', requireAdmin, (_req, res) => {
1976	res.json({ ok: true });
1977	});
1978
1979	// GET /api/v1/invites — hosted stub: no invite store
1980	app.get('/api/v1/invites', requireAdmin, (_req, res) => {
1981	res.json({ invites: [] });
1982	});
1983
1984	// POST /api/v1/invites — not supported on hosted (no invite store; full parity in Phase 2)
1985	app.post('/api/v1/invites', requireAdmin, (_req, res) => {
1986	res.status(400).json({
1987	error: 'Invites are not supported on hosted yet. Use self-hosted Hub for team invites, or wait for Phase 2.',
1988	code: 'NOT_SUPPORTED',
1989	});
1990	});
1991
1992	// Optional Muse read-only proxy (admin; Option C). 404 when MUSE_URL unset.
1993	app.get(
1994	'/api/v1/operator/muse/proxy',
1995	(req, res, next) => {
1996	if (!parseMuseConfigFromEnv()) {
1997	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
1998	}
1999	requireAdmin(req, res, next);
2000	},
2001	async (req, res) => {
2002	const cfg = parseMuseConfigFromEnv();
2003	if (!cfg) return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2004	const rel = typeof req.query.path === 'string' ? req.query.path.trim() : '';
2005	if (!rel) return res.status(400).json({ error: 'path query required', code: 'BAD_REQUEST' });
2006	const result = await fetchMuseProxiedGet({ config: cfg, relativePath: rel });
2007	if (!result.ok && result.code === 'BAD_REQUEST') {
2008	return res.status(400).json({ error: 'Invalid path', code: 'BAD_REQUEST' });
2009	}
2010	if (!result.ok && !result.body) {
2011	return res.status(result.status).json({ error: 'Bad gateway', code: result.code });
2012	}
2013	if (!result.ok && result.body && result.contentType) {
2014	res.status(result.status).set('Content-Type', result.contentType);
2015	res.set('X-Content-Type-Options', 'nosniff');
2016	return res.send(result.body);
2017	}
2018	if (result.ok && result.body) {
2019	res.status(200).set('Content-Type', result.contentType);
2020	res.set('X-Content-Type-Options', 'nosniff');
2021	return res.send(result.body);
2022	}
2023	return res.status(502).json({ error: 'Bad gateway', code: 'BAD_GATEWAY' });
2024	},
2025	);
2026
2027	// DELETE /api/v1/invites/:token — no-op on hosted
2028	app.delete('/api/v1/invites/:token', requireAdmin, (_req, res) => {
2029	res.json({ ok: true });
2030	});
2031
2032	// POST /api/v1/setup — no-op on hosted (vault is canister; nothing to persist)
2033	app.post('/api/v1/setup', (req, res) => {
2034	const uid = getUserId(req);
2035	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2036	res.json({ ok: true });
2037	});
2038
2039	// POST /api/v1/import — bridge runs importers and writes notes to canister when BRIDGE_URL is set
2040	app.post('/api/v1/import', async (req, res) => {
2041	const uid = getUserId(req);
2042	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2043	if (BRIDGE_URL) {
2044	if (!(await runBillingGate(req, res, getUserId))) return;
2045	const q = req.originalUrl.includes('?') ? req.originalUrl.slice(req.originalUrl.indexOf('?')) : '';
2046	await proxyImportToBridge(BRIDGE_URL, BRIDGE_URL + '/api/v1/import' + q, req, res);
2047	return;
2048	}
2049	res.status(501).json({
2050	error: 'Import is not yet available on hosted (set BRIDGE_URL for bridge-backed import).',
2051	code: 'NOT_AVAILABLE',
2052	});
2053	});
2054
2055	// POST /api/v1/import-url — JSON body; bridge runs URL importer (same auth as import).
2056	app.post('/api/v1/import-url', async (req, res) => {
2057	const uid = getUserId(req);
2058	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2059	if (BRIDGE_URL) {
2060	if (!(await runBillingGate(req, res, getUserId))) return;
2061	await proxyTo(BRIDGE_URL, BRIDGE_URL + '/api/v1/import-url', req, res);
2062	return;
2063	}
2064	res.status(501).json({
2065	error: 'Import URL is not available on hosted (set BRIDGE_URL for bridge-backed import).',
2066	code: 'NOT_AVAILABLE',
2067	});
2068	});
2069
2070	// GET /api/v1/notes/facets — aggregate from canister list (Hub filter dropdowns / overview parity)
2071	app.get('/api/v1/notes/facets', async (req, res) => {
2072	const uid = getUserId(req);
2073	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2074	if (!CANISTER_URL) {
2075	return res.json({ projects: [], tags: [], folders: [] });
2076	}
2077	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2078	const hctx = await getHostedAccessContext(req);
2079	const effective = (hctx && hctx.effective_canister_user_id) \|\| uid;
2080	if (hctx && Array.isArray(hctx.allowed_vault_ids) && !hctx.allowed_vault_ids.includes(vaultId)) {
2081	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
2082	}
2083	try {
2084	const url = `${CANISTER_URL}/api/v1/notes`;
2085	const upstream = await fetch(url, {
2086	method: 'GET',
2087	headers: {
2088	Accept: 'application/json',
2089	'x-user-id': effective,
2090	'x-actor-id': uid,
2091	'x-vault-id': vaultId,
2092	},
2093	});
2094	const text = await upstream.text();
2095	if (!upstream.ok) {
2096	console.warn('[gateway] facets canister list non-ok', upstream.status);
2097	return res.json({ projects: [], tags: [], folders: [] });
2098	}
2099	let data;
2100	try {
2101	data = text ? JSON.parse(text) : {};
2102	} catch (e) {
2103	console.warn('[gateway] facets canister list JSON parse', e?.message \|\| String(e));
2104	return res.json({ projects: [], tags: [], folders: [] });
2105	}
2106	const rows = Array.isArray(data.notes) ? data.notes : [];
2107	let notesForFacets = rows;
2108	const scope = hctx && hctx.scope && typeof hctx.scope === 'object' ? hctx.scope : null;
2109	if (scope && (scope.projects?.length \|\| scope.folders?.length)) {
2110	const withProj = rows.map((n) => ({
2111	path: n.path,
2112	project: materializeListFrontmatter(n.frontmatter).project ?? null,
2113	}));
2114	const scoped = applyScopeFilterToNotes(withProj, scope);
2115	const pathSet = new Set(scoped.map((n) => n.path).filter(Boolean));
2116	notesForFacets = rows.filter((n) => pathSet.has(n.path));
2117	}
2118	const facets = deriveFacetsFromCanisterNotes(notesForFacets);
2119	res.json(facets);
2120	} catch (e) {
2121	console.warn('[gateway] facets error', e?.message \|\| String(e));
2122	res.json({ projects: [], tags: [], folders: [] });
2123	}
2124	});
2125
2126	// GET /api/v1/vault/folders — no canister filesystem; UI falls back to inbox + custom path
2127	app.get('/api/v1/vault/folders', async (req, res) => {
2128	const uid = getUserId(req);
2129	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2130	if (!CANISTER_URL) {
2131	return res.json({ folders: ['inbox'] });
2132	}
2133	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2134	const hctx = await getHostedAccessContext(req);
2135	if (hctx && Array.isArray(hctx.allowed_vault_ids) && !hctx.allowed_vault_ids.includes(vaultId)) {
2136	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
2137	}
2138	res.json({ folders: ['inbox'] });
2139	});
2140
2141	app.get('/api/v1/note-outline', async (req, res) => {
2142	const uid = getUserId(req);
2143	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2144	if (!CANISTER_URL) {
2145	return res.status(503).json({ error: 'Hosted NoteOutline is not configured', code: 'SERVICE_UNAVAILABLE' });
2146	}
2147
2148	let requestedPath;
2149	try {
2150	requestedPath = normalizeGatewayNoteOutlinePath(req.query.path);
2151	} catch (e) {
2152	const err = sanitizedNoteOutlineGatewayError(e);
2153	return res.status(err.status).json({ error: err.error, code: err.code });
2154	}
2155
2156	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2157	const hctx = await getHostedAccessContext(req);
2158	if (hctx && Array.isArray(hctx.allowed_vault_ids) && !hctx.allowed_vault_ids.includes(vaultId)) {
2159	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
2160	}
2161	const effective =
2162	hctx && typeof hctx.effective_canister_user_id === 'string' && hctx.effective_canister_user_id
2163	? hctx.effective_canister_user_id
2164	: uid;
2165	const url = `${CANISTER_URL}/api/v1/notes/${encodeURIComponent(requestedPath)}`;
2166
2167	try {
2168	const upstream = await fetch(url, {
2169	method: 'GET',
2170	headers: {
2171	Accept: 'application/json',
2172	'x-user-id': effective,
2173	'x-actor-id': uid,
2174	'x-vault-id': vaultId,
2175	...canisterAuthHeaders(),
2176	},
2177	});
2178	const text = await upstream.text();
2179	if (upstream.status === 401 \|\| upstream.status === 403) {
2180	return res.status(403).json({ error: 'Forbidden', code: 'FORBIDDEN' });
2181	}
2182	if (upstream.status === 404) {
2183	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2184	}
2185	if (!upstream.ok) {
2186	return res.status(502).json({ error: `Upstream ${upstream.status}`, code: 'BAD_GATEWAY' });
2187	}
2188
2189	let note;
2190	try {
2191	note = text ? JSON.parse(text) : {};
2192	} catch {
2193	return res.status(502).json({ error: 'Invalid note response', code: 'BAD_GATEWAY' });
2194	}
2195
2196	const frontmatter = materializeListFrontmatter(note.frontmatter);
2197	const scope = scopeActiveForGateway(hctx) ? hctx.scope : null;
2198	if (scope) {
2199	const scoped = applyScopeFilterToNotes(
2200	[
2201	{
2202	path: requestedPath,
2203	project: frontmatter.project ?? null,
2204	},
2205	],
2206	scope
2207	);
2208	if (scoped.length === 0) {
2209	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2210	}
2211	}
2212
2213	return res.json(
2214	buildNoteOutline({
2215	path: requestedPath,
2216	frontmatter,
2217	body: note.body != null ? String(note.body) : '',
2218	})
2219	);
2220	} catch (e) {
2221	const err = sanitizedNoteOutlineGatewayError(e);
2222	return res.status(err.status).json({ error: err.error, code: err.code });
2223	}
2224	});
2225
2226	app.get('/api/v1/document-tree', async (req, res) => {
2227	const uid = getUserId(req);
2228	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2229	if (!CANISTER_URL) {
2230	return res.status(503).json({ error: 'Hosted DocumentTree is not configured', code: 'SERVICE_UNAVAILABLE' });
2231	}
2232
2233	let requestedPath;
2234	try {
2235	requestedPath = normalizeGatewayDocumentTreePath(req.query.path);
2236	} catch (e) {
2237	const err = sanitizedDocumentTreeGatewayError(e);
2238	return res.status(err.status).json({ error: err.error, code: err.code });
2239	}
2240
2241	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2242	const hctx = await getHostedAccessContext(req);
2243	if (hctx && Array.isArray(hctx.allowed_vault_ids) && !hctx.allowed_vault_ids.includes(vaultId)) {
2244	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
2245	}
2246	const effective =
2247	hctx && typeof hctx.effective_canister_user_id === 'string' && hctx.effective_canister_user_id
2248	? hctx.effective_canister_user_id
2249	: uid;
2250	const url = `${CANISTER_URL}/api/v1/notes/${encodeURIComponent(requestedPath)}`;
2251
2252	try {
2253	const upstream = await fetch(url, {
2254	method: 'GET',
2255	headers: {
2256	Accept: 'application/json',
2257	'x-user-id': effective,
2258	'x-actor-id': uid,
2259	'x-vault-id': vaultId,
2260	...canisterAuthHeaders(),
2261	},
2262	});
2263	const text = await upstream.text();
2264	if (upstream.status === 401 \|\| upstream.status === 403) {
2265	return res.status(403).json({ error: 'Forbidden', code: 'FORBIDDEN' });
2266	}
2267	if (upstream.status === 404) {
2268	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2269	}
2270	if (!upstream.ok) {
2271	return res.status(502).json({ error: `Upstream ${upstream.status}`, code: 'BAD_GATEWAY' });
2272	}
2273
2274	let note;
2275	try {
2276	note = text ? JSON.parse(text) : {};
2277	} catch {
2278	return res.status(502).json({ error: 'Invalid note response', code: 'BAD_GATEWAY' });
2279	}
2280
2281	const frontmatter = materializeListFrontmatter(note.frontmatter);
2282	const scope = scopeActiveForGateway(hctx) ? hctx.scope : null;
2283	if (scope) {
2284	const scoped = applyScopeFilterToNotes(
2285	[
2286	{
2287	path: requestedPath,
2288	project: frontmatter.project ?? null,
2289	},
2290	],
2291	scope
2292	);
2293	if (scoped.length === 0) {
2294	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2295	}
2296	}
2297
2298	return res.json(
2299	buildDocumentTree({
2300	path: requestedPath,
2301	frontmatter,
2302	body: note.body != null ? String(note.body) : '',
2303	})
2304	);
2305	} catch (e) {
2306	const err = sanitizedDocumentTreeGatewayError(e);
2307	return res.status(err.status).json({ error: err.error, code: err.code });
2308	}
2309	});
2310
2311	app.get('/api/v1/metadata-facets', async (req, res) => {
2312	const uid = getUserId(req);
2313	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2314	if (!CANISTER_URL) {
2315	return res.status(503).json({ error: 'Hosted MetadataFacets is not configured', code: 'SERVICE_UNAVAILABLE' });
2316	}
2317
2318	let requestedPath;
2319	try {
2320	requestedPath = normalizeGatewayMetadataFacetsPath(req.query.path);
2321	} catch (e) {
2322	const err = sanitizedMetadataFacetsGatewayError(e);
2323	return res.status(err.status).json({ error: err.error, code: err.code });
2324	}
2325
2326	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2327	const hctx = await getHostedAccessContext(req);
2328	if (hctx && Array.isArray(hctx.allowed_vault_ids) && !hctx.allowed_vault_ids.includes(vaultId)) {
2329	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
2330	}
2331	const effective =
2332	hctx && typeof hctx.effective_canister_user_id === 'string' && hctx.effective_canister_user_id
2333	? hctx.effective_canister_user_id
2334	: uid;
2335	const url = `${CANISTER_URL}/api/v1/notes/${encodeURIComponent(requestedPath)}`;
2336
2337	try {
2338	const upstream = await fetch(url, {
2339	method: 'GET',
2340	headers: {
2341	Accept: 'application/json',
2342	'x-user-id': effective,
2343	'x-actor-id': uid,
2344	'x-vault-id': vaultId,
2345	...canisterAuthHeaders(),
2346	},
2347	});
2348	const text = await upstream.text();
2349	if (upstream.status === 401 \|\| upstream.status === 403) {
2350	return res.status(403).json({ error: 'Forbidden', code: 'FORBIDDEN' });
2351	}
2352	if (upstream.status === 404) {
2353	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2354	}
2355	if (!upstream.ok) {
2356	return res.status(502).json({ error: `Upstream ${upstream.status}`, code: 'BAD_GATEWAY' });
2357	}
2358
2359	let note;
2360	try {
2361	note = text ? JSON.parse(text) : {};
2362	} catch {
2363	return res.status(502).json({ error: 'Invalid note response', code: 'BAD_GATEWAY' });
2364	}
2365
2366	const frontmatter = materializeListFrontmatter(note.frontmatter);
2367	const scope = scopeActiveForGateway(hctx) ? hctx.scope : null;
2368	if (scope) {
2369	const scoped = applyScopeFilterToNotes(
2370	[
2371	{
2372	path: requestedPath,
2373	project: frontmatter.project ?? null,
2374	},
2375	],
2376	scope
2377	);
2378	if (scoped.length === 0) {
2379	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2380	}
2381	}
2382
2383	return res.json(normalizeMetadataFacets(requestedPath, frontmatter));
2384	} catch (e) {
2385	const err = sanitizedMetadataFacetsGatewayError(e);
2386	return res.status(err.status).json({ error: err.error, code: err.code });
2387	}
2388	});
2389
2390	app.get('/api/v1/section-source', async (req, res) => {
2391	const uid = getUserId(req);
2392	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2393	if (!CANISTER_URL) {
2394	return res.status(503).json({ error: 'Hosted SectionSource is not configured', code: 'SERVICE_UNAVAILABLE' });
2395	}
2396
2397	let requestedPath;
2398	try {
2399	requestedPath = normalizeGatewaySectionSourcePath(req.query.path);
2400	} catch (e) {
2401	const err = sanitizedSectionSourceGatewayError(e);
2402	return res.status(err.status).json({ error: err.error, code: err.code });
2403	}
2404
2405	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2406	const hctx = await getHostedAccessContext(req);
2407	if (hctx && Array.isArray(hctx.allowed_vault_ids) && !hctx.allowed_vault_ids.includes(vaultId)) {
2408	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
2409	}
2410	const effective =
2411	hctx && typeof hctx.effective_canister_user_id === 'string' && hctx.effective_canister_user_id
2412	? hctx.effective_canister_user_id
2413	: uid;
2414	const url = `${CANISTER_URL}/api/v1/notes/${encodeURIComponent(requestedPath)}`;
2415
2416	try {
2417	const upstream = await fetch(url, {
2418	method: 'GET',
2419	headers: {
2420	Accept: 'application/json',
2421	'x-user-id': effective,
2422	'x-actor-id': uid,
2423	'x-vault-id': vaultId,
2424	...canisterAuthHeaders(),
2425	},
2426	});
2427	const text = await upstream.text();
2428	if (upstream.status === 401 \|\| upstream.status === 403) {
2429	return res.status(403).json({ error: 'Forbidden', code: 'FORBIDDEN' });
2430	}
2431	if (upstream.status === 404) {
2432	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2433	}
2434	if (!upstream.ok) {
2435	return res.status(502).json({ error: `Upstream ${upstream.status}`, code: 'BAD_GATEWAY' });
2436	}
2437
2438	let note;
2439	try {
2440	note = text ? JSON.parse(text) : {};
2441	} catch {
2442	return res.status(502).json({ error: 'Invalid note response', code: 'BAD_GATEWAY' });
2443	}
2444
2445	const frontmatter = materializeListFrontmatter(note.frontmatter);
2446	const scope = scopeActiveForGateway(hctx) ? hctx.scope : null;
2447	if (scope) {
2448	const scoped = applyScopeFilterToNotes(
2449	[
2450	{
2451	path: requestedPath,
2452	project: frontmatter.project ?? null,
2453	},
2454	],
2455	scope
2456	);
2457	if (scoped.length === 0) {
2458	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2459	}
2460	}
2461
2462	return res.json(
2463	buildSectionSource({
2464	path: requestedPath,
2465	frontmatter,
2466	body: note.body != null ? String(note.body) : '',
2467	})
2468	);
2469	} catch (e) {
2470	const err = sanitizedSectionSourceGatewayError(e);
2471	return res.status(err.status).json({ error: err.error, code: err.code });
2472	}
2473	});
2474
2475	/**
2476	* @param {Record<string, unknown>\|null} hctx
2477	*/
2478	function scopeActiveForGateway(hctx) {
2479	const s = hctx && hctx.scope && typeof hctx.scope === 'object' ? hctx.scope : null;
2480	return Boolean(s && (s.projects?.length \|\| s.folders?.length));
2481	}
2482
2483	/**
2484	* Normalize hosted canister note records before returning them to Hub clients.
2485	* The canister wire shape may store frontmatter as object JSON text; clients
2486	* should always receive the direct-read/list API contract object.
2487	* @param {unknown} note
2488	* @returns {unknown}
2489	*/
2490	function normalizeGatewayNoteFrontmatter(note) {
2491	if (!note \|\| typeof note !== 'object' \|\| Array.isArray(note)) return note;
2492	return {
2493	...note,
2494	frontmatter: materializeListFrontmatter(note.frontmatter),
2495	};
2496	}
2497
2498	async function gatewayProxyGetNotesList(req, res, uid, effective, hctx) {
2499	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2500	const raw = upstreamPathAndQuery(req);
2501	const qIdx = raw.indexOf('?');
2502	const searchPart = qIdx >= 0 ? raw.slice(qIdx + 1) : '';
2503	const params = new URLSearchParams(searchPart);
2504	const limit = Math.min(100, Math.max(0, parseInt(params.get('limit') \|\| '20', 10) \|\| 20));
2505	const offset = Math.max(0, parseInt(params.get('offset') \|\| '0', 10) \|\| 0);
2506	const scope = scopeActiveForGateway(hctx) ? hctx.scope : null;
2507	// Phase 12 — blockchain filters applied client-side (canister stores frontmatter as opaque JSON)
2508	const filterNetwork = (params.get('network') \|\| '').trim().toLowerCase();
2509	const filterWallet = (params.get('wallet_address') \|\| '').trim().toLowerCase();
2510	const filterPaymentStatus = (params.get('payment_status') \|\| '').trim().toLowerCase();
2511	const needsClientFilter = Boolean(scope \|\| filterNetwork \|\| filterWallet \|\| filterPaymentStatus);
2512	if (needsClientFilter) {
2513	params.set('limit', '10000');
2514	params.set('offset', '0');
2515	}
2516	// Remove Phase 12 params before forwarding to canister (canister ignores them, but keep URL clean)
2517	params.delete('network');
2518	params.delete('wallet_address');
2519	params.delete('payment_status');
2520	const fetchUrl = `${CANISTER_URL}/api/v1/notes${params.toString() ? `?${params.toString()}` : ''}`;
2521	try {
2522	const upstream = await fetch(fetchUrl, {
2523	method: 'GET',
2524	headers: {
2525	Accept: 'application/json',
2526	'x-user-id': effective,
2527	'x-actor-id': uid,
2528	'x-vault-id': vaultId,
2529	...canisterAuthHeaders(),
2530	},
2531	});
2532	const text = await upstream.text();
2533	const hop = filterUpstreamResponseHeadersForDecodedBody(upstream.headers.entries()).filter(
2534	([k]) => !['cache-control', 'etag', 'last-modified'].includes(k.toLowerCase()),
2535	);
2536	res.status(upstream.status).set(Object.fromEntries(hop));
2537	res.set('Cache-Control', 'private, no-store, must-revalidate');
2538	if (!upstream.ok \|\| !text) {
2539	res.send(text);
2540	return;
2541	}
2542	let data;
2543	try {
2544	data = JSON.parse(text);
2545	} catch (_) {
2546	res.send(text);
2547	return;
2548	}
2549	if (Array.isArray(data.notes)) {
2550	data = { ...data, notes: data.notes.map(normalizeGatewayNoteFrontmatter) };
2551	}
2552	if (needsClientFilter && Array.isArray(data.notes)) {
2553	let filtered = data.notes;
2554	// Scope filter (project/folder access control)
2555	if (scope) {
2556	const withProj = filtered.map((n) => ({
2557	path: n.path,
2558	project: materializeListFrontmatter(n.frontmatter).project ?? null,
2559	}));
2560	const kept = applyScopeFilterToNotes(withProj, scope);
2561	const keptPaths = new Set(kept.map((r) => r.path).filter(Boolean));
2562	filtered = filtered.filter((n) => n.path && keptPaths.has(n.path));
2563	}
2564	// Phase 12 blockchain filters
2565	if (filterNetwork \|\| filterWallet \|\| filterPaymentStatus) {
2566	filtered = filtered.filter((n) => {
2567	const fm = materializeListFrontmatter(n.frontmatter);
2568	if (filterNetwork && String(fm.network ?? '').trim().toLowerCase() !== filterNetwork) return false;
2569	if (filterWallet && String(fm.wallet_address ?? '').trim().toLowerCase() !== filterWallet) return false;
2570	if (filterPaymentStatus && String(fm.payment_status ?? '').trim().toLowerCase() !== filterPaymentStatus) return false;
2571	return true;
2572	});
2573	}
2574	const total = filtered.length;
2575	const page = filtered.slice(offset, offset + limit);
2576	res.json({ notes: page, total });
2577	return;
2578	}
2579	if (Array.isArray(data.notes)) {
2580	res.json(data);
2581	return;
2582	}
2583	res.send(text);
2584	} catch (e) {
2585	console.error('Gateway GET notes list error:', e.message);
2586	res.status(502).json({ error: 'Bad Gateway', code: 'BAD_GATEWAY' });
2587	}
2588	}
2589
2590	async function gatewayProxyGetNoteOne(req, res, uid, effective, hctx) {
2591	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2592	const url = CANISTER_URL + upstreamPathAndQuery(req);
2593	const scope = scopeActiveForGateway(hctx) ? hctx.scope : null;
2594	try {
2595	const upstream = await fetch(url, {
2596	method: 'GET',
2597	headers: {
2598	Accept: 'application/json',
2599	'x-user-id': effective,
2600	'x-actor-id': uid,
2601	'x-vault-id': vaultId,
2602	...canisterAuthHeaders(),
2603	},
2604	});
2605	const body = await upstream.text();
2606	if (upstream.status >= 400) {
2607	console.warn('[gateway] canister GET note:', upstream.status, 'url:', url.slice(0, 120));
2608	}
2609	const hop = filterUpstreamResponseHeadersForDecodedBody(upstream.headers.entries()).filter(
2610	([k]) => !['cache-control', 'etag', 'last-modified'].includes(k.toLowerCase()),
2611	);
2612	res.status(upstream.status).set(Object.fromEntries(hop));
2613	res.set('Cache-Control', 'private, no-store, must-revalidate');
2614	if (!scope \|\| upstream.status !== 200 \|\| !body) {
2615	if (upstream.status === 200 && body) {
2616	try {
2617	const note = JSON.parse(body);
2618	res.json(normalizeGatewayNoteFrontmatter(note));
2619	return;
2620	} catch (_) {
2621	// Preserve the upstream response when it is not valid JSON.
2622	}
2623	}
2624	res.send(body);
2625	return;
2626	}
2627	let note;
2628	try {
2629	note = normalizeGatewayNoteFrontmatter(JSON.parse(body));
2630	const withProj = {
2631	path: note.path,
2632	project: materializeListFrontmatter(note.frontmatter).project ?? null,
2633	};
2634	const filtered = applyScopeFilterToNotes([withProj], scope);
2635	if (filtered.length === 0) {
2636	res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
2637	return;
2638	}
2639	} catch (_) {
2640	res.send(body);
2641	return;
2642	}
2643	res.json(note);
2644	} catch (e) {
2645	console.error('Gateway GET note error:', e.message);
2646	res.status(502).json({ error: 'Bad Gateway', code: 'BAD_GATEWAY' });
2647	}
2648	}
2649
2650	const PROPOSAL_APPROVE_OR_DISCARD_RE = /^\/api\/v1\/proposals\/[^/]+\/(approve\|discard)\/?$/;
2651
2652	/**
2653	* Bridge / JWT actor role for proposal RBAC (canister only sees effective X-User-Id).
2654	* @param {import('express').Request} req
2655	* @param {Record<string, unknown>\|null} hctx
2656	* @returns {Promise<{ role: string, mayApproveProposals: boolean }>}
2657	*/
2658	async function resolveHostedActorRole(req, hctx) {
2659	const envFallback = process.env.HUB_EVALUATOR_MAY_APPROVE === '1';
2660	let role = 'member';
2661	let mayApproveProposals = false;
2662	if (hctx && typeof hctx.role === 'string') {
2663	role = hctx.role;
2664	if (typeof hctx.may_approve_proposals === 'boolean') {
2665	mayApproveProposals = hctx.may_approve_proposals;
2666	} else if (role === 'evaluator') {
2667	mayApproveProposals = envFallback;
2668	}
2669	} else if (BRIDGE_URL && req.headers.authorization) {
2670	let bridgeResolved = false;
2671	try {
2672	const roleRes = await fetch(BRIDGE_URL + '/api/v1/role', {
2673	method: 'GET',
2674	headers: { Authorization: req.headers.authorization, Accept: 'application/json' },
2675	});
2676	if (roleRes.ok) {
2677	const data = await roleRes.json();
2678	if (data.role) {
2679	role = data.role;
2680	bridgeResolved = true;
2681	}
2682	if (typeof data.may_approve_proposals === 'boolean') {
2683	mayApproveProposals = data.may_approve_proposals;
2684	} else if (role === 'evaluator') {
2685	mayApproveProposals = envFallback;
2686	}
2687	}
2688	} catch (_) {}
2689	// Bridge unreachable or rejected the JWT (e.g. SESSION_SECRET mismatch after a redeploy).
2690	// Fall back to the JWT payload role so the gateway owner is never locked out by bridge state.
2691	if (!bridgeResolved) {
2692	try {
2693	const auth = req.headers.authorization;
2694	const token = auth && auth.startsWith('Bearer ') ? auth.slice(7) : null;
2695	if (token && SESSION_SECRET) {
2696	const payload = jwt.verify(token, SESSION_SECRET);
2697	role = payload.role \|\| roleForSub(payload.sub);
2698	mayApproveProposals = role === 'admin' \|\| (role === 'evaluator' && envFallback);
2699	}
2700	} catch (_) {}
2701	}
2702	} else {
2703	try {
2704	const auth = req.headers.authorization;
2705	const token = auth && auth.startsWith('Bearer ') ? auth.slice(7) : null;
2706	if (token && SESSION_SECRET) {
2707	const payload = jwt.verify(token, SESSION_SECRET);
2708	role = payload.role \|\| roleForSub(payload.sub);
2709	mayApproveProposals = role === 'admin' \|\| (role === 'evaluator' && envFallback);
2710	}
2711	} catch (_) {}
2712	}
2713	// Gateway-level admin override: HUB_ADMIN_USER_IDS is the authoritative owner list.
2714	// A sub in that list is always admin — the gateway owner must never be locked out by a
2715	// bridge state reset, role-store loss, or SESSION_SECRET mismatch between gateway and bridge.
2716	const actorSub = getUserId(req);
2717	if (actorSub && role !== 'admin' && roleForSub(actorSub) === 'admin') {
2718	role = 'admin';
2719	mayApproveProposals = true;
2720	}
2721	return { role, mayApproveProposals };
2722	}
2723
2724	/**
2725	* Approve/discard: enforce actor role on gateway (canister only sees effective X-User-Id).
2726	* @param {import('express').Request} req
2727	* @param {import('express').Response} res
2728	* @param {string} pathNoQuery
2729	* @param {string} method
2730	* @param {Record<string, unknown>\|null} hctx from getHostedAccessContext (null if no bridge / not delegated)
2731	*/
2732	async function assertHostedProposalApproveDiscard(req, res, pathNoQuery, method, hctx) {
2733	if (method !== 'POST' \|\| !PROPOSAL_APPROVE_OR_DISCARD_RE.test(pathNoQuery)) return true;
2734
2735	const uid = getUserId(req);
2736	if (!uid) {
2737	res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2738	return false;
2739	}
2740
2741	const { role, mayApproveProposals } = await resolveHostedActorRole(req, hctx);
2742
2743	if (/\/discard\/?$/.test(pathNoQuery)) {
2744	if (role !== 'admin') {
2745	res.status(403).json({ error: 'Discard requires admin.', code: 'FORBIDDEN' });
2746	return false;
2747	}
2748	return true;
2749	}
2750
2751	const canApprove = role === 'admin' \|\| (role === 'evaluator' && mayApproveProposals);
2752	if (!canApprove) {
2753	res.status(403).json({
2754	error:
2755	'Approve requires admin, or an evaluator with approve permission (per-user in Team, or HUB_EVALUATOR_MAY_APPROVE=1 when no per-user value).',
2756	code: 'FORBIDDEN',
2757	});
2758	return false;
2759	}
2760	return true;
2761	}
2762
2763	/**
2764	* Fetch the current note count for a user from the canister.
2765	* Used by the billing storage cap gate before note CREATE.
2766	* Fails open — returns 0 on any error so the gate never blocks due to a canister outage.
2767	*
2768	* @param {string} userId
2769	* @param {import('express').Request} req
2770	* @returns {Promise<number>}
2771	*/
2772	async function getNoteCountForUser(userId, req) {
2773	if (!CANISTER_URL) return 0;
2774	try {
2775	let vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2776	const pathOnly = effectiveRequestPath(req).replace(/\/+$/, '') \|\| '/';
2777	if (req.method === 'POST' && pathOnly === '/api/v1/notes/copy') {
2778	const b = req.body && typeof req.body === 'object' ? req.body : {};
2779	const toV = typeof b.to_vault_id === 'string' ? b.to_vault_id.replace(/\\/g, '/').trim() : '';
2780	if (toV) vaultId = toV;
2781	}
2782	const hctx = await getHostedAccessContext(req);
2783	const effective =
2784	hctx && typeof hctx.effective_canister_user_id === 'string' && hctx.effective_canister_user_id
2785	? hctx.effective_canister_user_id
2786	: userId;
2787	const url = `${CANISTER_URL}/api/v1/notes?limit=1&offset=0`;
2788	const upstream = await fetch(url, {
2789	method: 'GET',
2790	headers: {
2791	Accept: 'application/json',
2792	'x-user-id': effective,
2793	'x-actor-id': userId,
2794	'x-vault-id': vaultId,
2795	...canisterAuthHeaders(),
2796	},
2797	});
2798	if (!upstream.ok) return 0;
2799	const data = await upstream.json();
2800	const total = typeof data.total === 'number' ? data.total : (Array.isArray(data.notes) ? data.notes.length : 0);
2801	return Math.max(0, Math.floor(total));
2802	} catch (_) {
2803	return 0;
2804	}
2805	}
2806
2807	async function proxyToCanister(req, res) {
2808	const uid = getUserId(req);
2809	if (!uid) {
2810	return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
2811	}
2812	const pathOnly = effectiveRequestPath(req);
2813	const pathNoQuery = pathPartNoQuery(req);
2814	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
2815	const hctx = await getHostedAccessContext(req);
2816	if (!(await assertHostedProposalApproveDiscard(req, res, pathNoQuery, req.method, hctx))) return;
2817	const effective =
2818	hctx && typeof hctx.effective_canister_user_id === 'string' && hctx.effective_canister_user_id
2819	? hctx.effective_canister_user_id
2820	: uid;
2821	if (hctx && Array.isArray(hctx.allowed_vault_ids) && !hctx.allowed_vault_ids.includes(vaultId)) {
2822	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
2823	}
2824
2825	if (req.method === 'GET' && pathOnly === '/api/v1/notes') {
2826	return gatewayProxyGetNotesList(req, res, uid, effective, hctx);
2827	}
2828	const noteSubPrefix = '/api/v1/notes/';
2829	if (
2830	req.method === 'GET' &&
2831	pathOnly.startsWith(noteSubPrefix) &&
2832	pathOnly !== '/api/v1/notes/facets'
2833	) {
2834	const rest = pathOnly.slice(noteSubPrefix.length);
2835	if (rest) {
2836	return gatewayProxyGetNoteOne(req, res, uid, effective, hctx);
2837	}
2838	}
2839
2840	const url = CANISTER_URL + upstreamPathAndQuery(req);
2841	const headers = {
2842	host: new URL(CANISTER_URL).host,
2843	'x-user-id': effective,
2844	'x-actor-id': uid,
2845	'x-vault-id': req.headers['x-vault-id'] \|\| 'default',
2846	...canisterAuthHeaders(),
2847	};
2848	// Allowlist: only forward safe body/content headers; canister auth is via x-user-id + x-gateway-auth.
2849	// Never forward origin, referer, cookies, authorization, or other proxy headers to the canister.
2850	for (const k of PROXY_HEADER_ALLOWLIST) {
2851	if (req.headers[k] !== undefined) headers[k] = req.headers[k];
2852	}
2853	const opts = { method: req.method, headers };
2854	let bodyOut = req.body;
2855	const pathOnlyForBody = pathPartNoQuery(req);
2856	const dataDir = path.join(projectRoot, 'data');
2857	let hostedLlmPrefs = null;
2858	if (
2859	req.method === 'POST' &&
2860	(pathOnlyForBody === '/api/v1/proposals' \|\| pathOnlyForBody === '/api/v1/proposals/')
2861	) {
2862	hostedLlmPrefs = await loadHostedProposalLlmPrefs();
2863	}
2864	// Improvement B: AIR attestation for hosted gateway note writes.
2865	// Guarded by KNOWTATION_AIR_ENDPOINT being set; always non-blocking (gateway has no air.required config).
2866	let gatewayAirId = null;
2867	if (
2868	process.env.KNOWTATION_AIR_ENDPOINT &&
2869	bodyOut !== undefined &&
2870	typeof bodyOut === 'object' &&
2871	!Buffer.isBuffer(bodyOut) &&
2872	isNoteWriteRequest(req.method, pathOnlyForBody)
2873	) {
2874	try {
2875	const notePath =
2876	req.method === 'POST'
2877	? (typeof bodyOut.path === 'string' ? bodyOut.path.replace(/\\/g, '/') : '')
2878	: pathOnlyForBody
2879	.slice('/api/v1/notes/'.length)
2880	.split('/')
2881	.map(decodeURIComponent)
2882	.join('/');
2883	const { attestBeforeWrite: gwAttest } = await import('../../lib/air.mjs');
2884	const airId = await gwAttest(
2885	{ air: { enabled: true, required: false, endpoint: process.env.KNOWTATION_AIR_ENDPOINT } },
2886	notePath
2887	);
2888	if (airId && airId !== 'air-placeholder-write') {
2889	gatewayAirId = airId;
2890	}
2891	} catch (e) {
2892	// Never let an AIR failure block a hosted write; log and continue.
2893	console.error('[gateway] AIR attestation error (non-fatal):', e?.message \|\| String(e));
2894	}
2895	}
2896
2897	if (
2898	bodyOut !== undefined &&
2899	typeof bodyOut === 'object' &&
2900	!Buffer.isBuffer(bodyOut) &&
2901	isPostApiV1Notes(req.method, pathOnlyForBody)
2902	) {
2903	bodyOut = mergeHostedNoteBodyForCanister(bodyOut, uid, gatewayAirId);
2904	} else if (
2905	gatewayAirId &&
2906	bodyOut !== undefined &&
2907	typeof bodyOut === 'object' &&
2908	!Buffer.isBuffer(bodyOut) &&
2909	req.method === 'PUT' &&
2910	pathOnlyForBody.startsWith('/api/v1/notes/')
2911	) {
2912	// PUT note write: inject air_id into frontmatter alongside existing fields
2913	bodyOut = mergeHostedNoteBodyForCanister(bodyOut, uid, gatewayAirId);
2914	}
2915	if (bodyOut !== undefined && typeof bodyOut === 'object' && !Buffer.isBuffer(bodyOut)) {
2916	bodyOut = augmentProposalEvaluationBodyForCanister(req.method, pathOnlyForBody, bodyOut);
2917	const policyOpts =
2918	hostedLlmPrefs != null
2919	? { evaluationRequired: effectiveHostedEvaluationRequired(hostedLlmPrefs, dataDir) }
2920	: {};
2921	bodyOut = augmentProposalCreateForHosted(req.method, pathOnlyForBody, bodyOut, dataDir, policyOpts);
2922	if (req.method === 'POST') {
2923	const approveId = proposalIdFromApprovePath(pathOnlyForBody);
2924	if (approveId) {
2925	try {
2926	const museCfg = parseMuseConfigFromEnv();
2927	const resolved = await resolveExternalRefForApprove({
2928	clientRef: bodyOut.external_ref,
2929	proposalId: approveId,
2930	vaultId,
2931	config: museCfg,
2932	logWarn: (msg, extra) => console.warn(msg, extra != null ? JSON.stringify(extra) : ''),
2933	});
2934	if (resolved) {
2935	bodyOut = { ...bodyOut, external_ref: resolved };
2936	}
2937	} catch (e) {
2938	console.warn('[gateway] muse approve merge (non-fatal):', e?.message \|\| String(e));
2939	}
2940	}
2941	}
2942	}
2943	if (req.method !== 'GET' && req.method !== 'HEAD' && bodyOut !== undefined) {
2944	opts.body = typeof bodyOut === 'string' ? bodyOut : JSON.stringify(bodyOut);
2945	stripStaleOutboundBodyHeaders(headers);
2946	}
2947	try {
2948	const upstream = await fetch(url, opts);
2949	const body = await upstream.text();
2950	// For a successful proposal CREATE, extract path+body so the hints job can skip
2951	// its own canister GET (saves one ICP round trip, ~1–3 s, from the hints path).
2952	let parsedProposalData = null;
2953	if (
2954	req.method === 'POST' &&
2955	(pathOnlyForBody === '/api/v1/proposals' \|\| pathOnlyForBody === '/api/v1/proposals/') &&
2956	upstream.status >= 200 && upstream.status < 300
2957	) {
2958	try {
2959	const j = JSON.parse(body);
2960	const merged = proposalDataForHostedReviewHintsFromCreate(j, bodyOut);
2961	if (merged) parsedProposalData = merged;
2962	} catch (_) {}
2963	}
2964	try {
2965	await maybeScheduleHostedProposalReviewHints({
2966	method: req.method,
2967	pathOnly: pathOnlyForBody,
2968	upstreamStatus: upstream.status,
2969	responseText: body,
2970	canisterUrl: CANISTER_URL,
2971	effectiveUserId: effective,
2972	actorUserId: uid,
2973	vaultId,
2974	hintsEnabled: hostedLlmPrefs ? effectiveHostedReviewHints(hostedLlmPrefs) : false,
2975	proposalData: parsedProposalData,
2976	});
2977	} catch (e) {
2978	// Never let a hints failure affect the primary proxy response.
2979	console.error('[gateway] hints exception (non-fatal):', e?.message \|\| String(e));
2980	}
2981	if (upstream.status >= 400 && req.method === 'GET' && url.includes('/api/v1/notes/')) {
2982	console.warn('[gateway] canister GET note:', upstream.status, 'url:', url.slice(0, 120));
2983	}
2984	if (
2985	upstream.status === 404 &&
2986	req.method === 'POST' &&
2987	/\/api\/v1\/proposals\/[^/]+\/evaluation\/?(\?\|$)/.test(pathOnlyForBody)
2988	) {
2989	console.warn(
2990	'[gateway] canister returned 404 for POST …/evaluation. If the body is {"error":"Not found","code":"NOT_FOUND"}, the hub canister on mainnet likely predates the evaluation route or HTTP upgrade for it — redeploy `hub` from this repo (`hub/icp/README.md` §ICP HTTP gateway behavior).',
2991	);
2992	}
2993	const hop = filterUpstreamResponseHeadersForDecodedBody(upstream.headers.entries()).filter(
2994	([k]) => !['cache-control', 'etag', 'last-modified'].includes(k.toLowerCase()),
2995	);
2996	res.status(upstream.status).set(Object.fromEntries(hop));
2997	res.set('Cache-Control', 'private, no-store, must-revalidate');
2998	res.send(body);
2999	} catch (e) {
3000	console.error('Gateway proxy error:', e.message);
3001	res.status(502).json({ error: 'Bad Gateway', code: 'BAD_GATEWAY' });
3002	}
3003	}
3004
3005	// Bulk metadata by effective project slug (canister orchestration; not a canister route)
3006	app.post('/api/v1/notes/delete-by-project', async (req, res) => {
3007	if (!(await runBillingGate(req, res, getUserId))) return;
3008	return metadataBulkHandlers.deleteByProject(req, res);
3009	});
3010	app.post('/api/v1/notes/rename-project', async (req, res) => {
3011	if (!(await runBillingGate(req, res, getUserId))) return;
3012	return metadataBulkHandlers.renameProject(req, res);
3013	});
3014
3015	/** Hosted Enrich: gateway runs LLM and POSTs to canister (not proxied as opaque POST). */
3016	app.post('/api/v1/proposals/:proposalId/enrich', async (req, res) => {
3017	// Express 4 does not auto-catch async route handler exceptions; wrap everything so a
3018	// rejected promise never leaves the request hanging until Netlify's Lambda timeout.
3019	try {
3020	if (!(await runBillingGate(req, res, getUserId))) return;
3021	const uid = getUserId(req);
3022	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
3023	const proposalId = req.params.proposalId;
3024	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
3025	const hctx = await getHostedAccessContext(req);
3026	if (hctx && Array.isArray(hctx.allowed_vault_ids) && !hctx.allowed_vault_ids.includes(vaultId)) {
3027	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
3028	}
3029	const { role } = await resolveHostedActorRole(req, hctx);
3030	if (role === 'viewer') {
3031	return res.status(403).json({ error: 'This action requires a different role.', code: 'FORBIDDEN' });
3032	}
3033	const effective =
3034	hctx && typeof hctx.effective_canister_user_id === 'string' && hctx.effective_canister_user_id
3035	? hctx.effective_canister_user_id
3036	: uid;
3037	const llmPrefs = await loadHostedProposalLlmPrefs();
3038	const enrichEnabled = effectiveHostedEnrich(llmPrefs);
3039	// Diagnostic: log which LLM provider will be used (visible in Netlify function logs).
3040	console.log(
3041	'[gateway/enrich] proposalId=%s enrichEnabled=%s provider=%s',
3042	proposalId,
3043	enrichEnabled,
3044	process.env.OPENAI_API_KEY ? 'openai' : process.env.ANTHROPIC_API_KEY ? 'anthropic' : 'ollama(NO KEY)',
3045	);
3046	const out = await runHostedProposalEnrichAndPost({
3047	canisterUrl: CANISTER_URL,
3048	effectiveUserId: effective,
3049	actorUserId: uid,
3050	vaultId,
3051	proposalId,
3052	enrichEnabled,
3053	});
3054	if (!out.ok) {
3055	if (out.status === 404 && out.code === 'NOT_FOUND') {
3056	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
3057	}
3058	if (out.status === 404) {
3059	return res.status(404).json({ error: 'Proposal not found', code: 'NOT_FOUND' });
3060	}
3061	if (out.status === 400) {
3062	return res.status(400).json({ error: out.detail \|\| 'Bad request', code: out.code \|\| 'BAD_REQUEST' });
3063	}
3064	return res.status(out.status \|\| 500).json({
3065	error: out.detail \|\| out.code \|\| 'Enrich failed',
3066	code: out.code \|\| 'RUNTIME_ERROR',
3067	});
3068	}
3069	// Return immediately — the frontend calls openProposal() + loadProposals() after this
3070	// which re-fetches the updated proposal. Eliminating the extra canister GET here removes
3071	// one full ICP round trip (~1–3 s) from the critical path and prevents Netlify timeout.
3072	return res.set('Cache-Control', 'private, no-store, must-revalidate').json({ ok: true });
3073	} catch (e) {
3074	console.error('[gateway/enrich] unhandled exception:', e?.stack \|\| e?.message \|\| e);
3075	if (!res.headersSent) {
3076	res.status(500).json({ error: e?.message \|\| 'Internal error', code: 'INTERNAL_ERROR' });
3077	}
3078	}
3079	});
3080
3081	// ---------------------------------------------------------------------------
3082	// AIR Improvement D — built-in attestation endpoint
3083	// ---------------------------------------------------------------------------
3084
3085	app.post('/api/v1/attest', async (req, res) => {
3086	const uid = getUserId(req);
3087	if (!uid) {
3088	return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
3089	}
3090	if (!isAttestationConfigured()) {
3091	return res.status(503).json({
3092	error: 'Attestation service not configured (ATTESTATION_SECRET missing or too short).',
3093	code: 'NOT_CONFIGURED',
3094	});
3095	}
3096	const body = req.body && typeof req.body === 'object' ? req.body : {};
3097	const action = typeof body.action === 'string' ? body.action.trim() : '';
3098	if (!action) {
3099	return res.status(400).json({ error: 'action is required', code: 'BAD_REQUEST' });
3100	}
3101	const notePath = typeof body.path === 'string' ? body.path : '';
3102	const contentHash = typeof body.content_hash === 'string' ? body.content_hash : null;
3103	try {
3104	const result = await createAttestation(action, notePath, contentHash);
3105	return res.json(result);
3106	} catch (e) {
3107	console.error('[gateway] POST /api/v1/attest error:', e?.message \|\| e);
3108	return res.status(500).json({ error: 'Attestation failed', code: 'INTERNAL_ERROR' });
3109	}
3110	});
3111
3112	app.get('/api/v1/attest/:id', async (req, res) => {
3113	if (!isAttestationConfigured()) {
3114	return res.status(503).json({
3115	error: 'Attestation service not configured (ATTESTATION_SECRET missing or too short).',
3116	code: 'NOT_CONFIGURED',
3117	});
3118	}
3119	const id = req.params.id;
3120	if (!id \|\| !id.startsWith('air-')) {
3121	return res.status(400).json({ error: 'Invalid attestation id format', code: 'BAD_REQUEST' });
3122	}
3123	try {
3124	const result = await verifyAttestation(id);
3125	if (!result.record) {
3126	return res.status(404).json({ error: 'Attestation not found', code: 'NOT_FOUND' });
3127	}
3128	return res.json(result);
3129	} catch (e) {
3130	console.error('[gateway] GET /api/v1/attest/:id error:', e?.message \|\| e);
3131	return res.status(500).json({ error: 'Verification failed', code: 'INTERNAL_ERROR' });
3132	}
3133	});
3134
3135	// ---------------------------------------------------------------------------
3136	// AIR Improvement E — ICP blockchain anchor verification + reconciliation
3137	// ---------------------------------------------------------------------------
3138
3139	app.get('/api/v1/attest/:id/verify', async (req, res) => {
3140	if (!isAttestationConfigured()) {
3141	return res.status(503).json({
3142	error: 'Attestation service not configured (ATTESTATION_SECRET missing or too short).',
3143	code: 'NOT_CONFIGURED',
3144	});
3145	}
3146	const id = req.params.id;
3147	if (!id \|\| !id.startsWith('air-')) {
3148	return res.status(400).json({ error: 'Invalid attestation id format', code: 'BAD_REQUEST' });
3149	}
3150	try {
3151	const result = await verifyWithIcp(id);
3152	if (!result.sources.blobs.found && !result.sources.icp.found) {
3153	return res.status(404).json({ error: 'Attestation not found', code: 'NOT_FOUND', ...result });
3154	}
3155	return res.json(result);
3156	} catch (e) {
3157	console.error('[gateway] GET /api/v1/attest/:id/verify error:', e?.message \|\| e);
3158	return res.status(500).json({ error: 'Verification failed', code: 'INTERNAL_ERROR' });
3159	}
3160	});
3161
3162	app.post('/api/v1/attest/anchor-pending', requireAdmin, async (req, res) => {
3163	if (!isAttestationConfigured()) {
3164	return res.status(503).json({
3165	error: 'Attestation service not configured (ATTESTATION_SECRET missing or too short).',
3166	code: 'NOT_CONFIGURED',
3167	});
3168	}
3169	const body = req.body && typeof req.body === 'object' ? req.body : {};
3170	const ids = Array.isArray(body.ids) ? body.ids.filter((x) => typeof x === 'string' && x.startsWith('air-')) : [];
3171	if (ids.length === 0) {
3172	return res.status(400).json({ error: 'ids array with air-* entries is required', code: 'BAD_REQUEST' });
3173	}
3174	if (ids.length > 100) {
3175	return res.status(400).json({ error: 'Maximum 100 IDs per batch', code: 'BAD_REQUEST' });
3176	}
3177	try {
3178	const result = await anchorPendingAttestations(ids);
3179	return res.json(result);
3180	} catch (e) {
3181	console.error('[gateway] POST /api/v1/attest/anchor-pending error:', e?.message \|\| e);
3182	return res.status(500).json({ error: 'Anchor failed', code: 'INTERNAL_ERROR' });
3183	}
3184	});
3185
3186	/**
3187	* Hosted: single-note export for Hub UI (POST /api/v1/export). Self-hosted Node Hub implements
3188	* this with filesystem; the ICP canister only supports GET /api/v1/export (full vault JSON), so
3189	* POST was returning 404 from the canister. We fetch the note and build the same download payload
3190	* as lib/export.mjs.
3191	*/
3192	app.post('/api/v1/export', async (req, res) => {
3193	if (!CANISTER_URL) {
3194	return res.status(503).json({ error: 'Hosted export not configured', code: 'SERVICE_UNAVAILABLE' });
3195	}
3196	if (!(await runBillingGate(req, res, getUserId, { getNoteCount: getNoteCountForUser }))) return;
3197	const uid = getUserId(req);
3198	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
3199	const body = req.body && typeof req.body === 'object' ? req.body : {};
3200	const notePath = typeof body.path === 'string' ? body.path.replace(/\\/g, '/').trim() : '';
3201	const fmt = body.format === 'html' ? 'html' : 'md';
3202	if (!notePath \|\| notePath.includes('..') \|\| notePath.startsWith('/')) {
3203	return res.status(400).json({ error: 'path required', code: 'BAD_REQUEST' });
3204	}
3205	const vaultId = String(req.headers['x-vault-id'] \|\| 'default').trim() \|\| 'default';
3206	const hctx = await getHostedAccessContext(req);
3207	if (hctx && Array.isArray(hctx.allowed_vault_ids) && !hctx.allowed_vault_ids.includes(vaultId)) {
3208	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
3209	}
3210	const effective =
3211	hctx && typeof hctx.effective_canister_user_id === 'string' && hctx.effective_canister_user_id
3212	? hctx.effective_canister_user_id
3213	: uid;
3214	const enc = notePath.split('/').map(encodeURIComponent).join('/');
3215	const url = `${CANISTER_URL}/api/v1/notes/${enc}`;
3216	let upstream;
3217	try {
3218	upstream = await fetch(url, {
3219	method: 'GET',
3220	headers: {
3221	Accept: 'application/json',
3222	'x-user-id': effective,
3223	'x-actor-id': uid,
3224	'x-vault-id': vaultId,
3225	...canisterAuthHeaders(),
3226	},
3227	});
3228	} catch (e) {
3229	console.error('[gateway] export fetch note:', e?.message \|\| e);
3230	return res.status(502).json({ error: 'Bad Gateway', code: 'BAD_GATEWAY' });
3231	}
3232	const text = await upstream.text();
3233	if (upstream.status === 404) {
3234	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
3235	}
3236	if (!upstream.ok) {
3237	return res.status(upstream.status).type('application/json').send(text);
3238	}
3239	let note;
3240	try {
3241	note = JSON.parse(text);
3242	} catch {
3243	return res.status(502).json({ error: 'Invalid note response', code: 'BAD_GATEWAY' });
3244	}
3245	const scope = scopeActiveForGateway(hctx) ? hctx.scope : null;
3246	if (scope) {
3247	const withProj = {
3248	path: note.path,
3249	project: materializeListFrontmatter(note.frontmatter).project ?? null,
3250	};
3251	const filtered = applyScopeFilterToNotes([withProj], scope);
3252	if (filtered.length === 0) {
3253	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
3254	}
3255	}
3256	const fm = materializeListFrontmatter(note.frontmatter);
3257	const { content, filename } = exportNoteRecordToContent(
3258	{ body: note.body != null ? String(note.body) : '', frontmatter: fm },
3259	note.path \|\| notePath,
3260	{ format: fmt },
3261	);
3262	res.set('Cache-Control', 'private, no-store, must-revalidate');
3263	return res.json({ content, filename });
3264	});
3265
3266	/**
3267	* Cross-vault copy/move (hosted gateway): GET note from canister vault A, POST to vault B, optional DELETE on A.
3268	* Conflicts: if `path` already exists in the target vault, the write overwrites (same as POST /notes).
3269	* After success, triggers bridge Re-index for the target vault and, when moving, the source vault (fire-and-forget).
3270	*/
3271	app.post('/api/v1/notes/copy', async (req, res) => {
3272	if (!CANISTER_URL) {
3273	return res.status(503).json({ error: 'Hosted copy not configured', code: 'SERVICE_UNAVAILABLE' });
3274	}
3275	if (!(await runBillingGate(req, res, getUserId, { getNoteCount: getNoteCountForUser }))) return;
3276	const uid = getUserId(req);
3277	if (!uid) return res.status(401).json({ error: 'Unauthorized', code: 'UNAUTHORIZED' });
3278	const authHeader = req.headers.authorization \|\| '';
3279	const body = req.body && typeof req.body === 'object' ? req.body : {};
3280	const fromVault = typeof body.from_vault_id === 'string' ? body.from_vault_id.replace(/\\/g, '/').trim() : '';
3281	const toVault = typeof body.to_vault_id === 'string' ? body.to_vault_id.replace(/\\/g, '/').trim() : '';
3282	const notePath = typeof body.path === 'string' ? body.path.replace(/\\/g, '/').trim() : '';
3283	const deleteSource = body.delete_source === true;
3284	if (!fromVault \|\| !toVault \|\| !notePath \|\| notePath.includes('..') \|\| notePath.startsWith('/')) {
3285	return res.status(400).json({
3286	error: 'from_vault_id, to_vault_id, and path are required (vault-relative path)',
3287	code: 'BAD_REQUEST',
3288	});
3289	}
3290	if (fromVault === toVault) {
3291	return res.status(400).json({ error: 'from_vault_id and to_vault_id must differ', code: 'BAD_REQUEST' });
3292	}
3293	/** @type {Record<string, unknown>\|null} */
3294	let hctxFrom = null;
3295	if (BRIDGE_URL) {
3296	hctxFrom = await fetchHostedAccessContextForVault(authHeader, fromVault);
3297	if (!hctxFrom) {
3298	return res.status(403).json({ error: 'Hosted workspace context unavailable.', code: 'FORBIDDEN' });
3299	}
3300	if (Array.isArray(hctxFrom.allowed_vault_ids)) {
3301	if (!hctxFrom.allowed_vault_ids.includes(fromVault) \|\| !hctxFrom.allowed_vault_ids.includes(toVault)) {
3302	return res.status(403).json({ error: 'Access to this vault is not allowed.', code: 'FORBIDDEN' });
3303	}
3304	}
3305	}
3306	const { role } = await resolveHostedActorRole(req, hctxFrom);
3307	if (role === 'viewer') {
3308	return res.status(403).json({ error: 'This action requires editor or admin.', code: 'FORBIDDEN' });
3309	}
3310	const effective =
3311	hctxFrom && typeof hctxFrom.effective_canister_user_id === 'string' && hctxFrom.effective_canister_user_id
3312	? hctxFrom.effective_canister_user_id
3313	: uid;
3314	const enc = notePath.split('/').map(encodeURIComponent).join('/');
3315	const getUrl = `${CANISTER_URL}/api/v1/notes/${enc}`;
3316	let upstream;
3317	try {
3318	upstream = await fetch(getUrl, {
3319	method: 'GET',
3320	headers: {
3321	Accept: 'application/json',
3322	'x-user-id': effective,
3323	'x-actor-id': uid,
3324	'x-vault-id': fromVault,
3325	...canisterAuthHeaders(),
3326	},
3327	});
3328	} catch (e) {
3329	console.error('[gateway] notes/copy fetch source:', e?.message \|\| e);
3330	return res.status(502).json({ error: 'Bad Gateway', code: 'BAD_GATEWAY' });
3331	}
3332	const getText = await upstream.text();
3333	if (upstream.status === 404) {
3334	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
3335	}
3336	if (!upstream.ok) {
3337	return res.status(upstream.status).type('application/json').send(getText);
3338	}
3339	let note;
3340	try {
3341	note = JSON.parse(getText);
3342	} catch {
3343	return res.status(502).json({ error: 'Invalid note response', code: 'BAD_GATEWAY' });
3344	}
3345	const scope = scopeActiveForGateway(hctxFrom) ? hctxFrom.scope : null;
3346	if (scope) {
3347	const withProj = {
3348	path: note.path,
3349	project: materializeListFrontmatter(note.frontmatter).project ?? null,
3350	};
3351	const filtered = applyScopeFilterToNotes([withProj], scope);
3352	if (filtered.length === 0) {
3353	return res.status(404).json({ error: 'Not found', code: 'NOT_FOUND' });
3354	}
3355	}
3356	const outPath = note.path \|\| notePath;
3357	let fmRaw = note.frontmatter;
3358	if (typeof fmRaw === 'string') {
3359	try {
3360	fmRaw = fmRaw.trim() ? JSON.parse(fmRaw) : {};
3361	} catch {
3362	fmRaw = {};
3363	}
3364	}
3365	if (!fmRaw \|\| typeof fmRaw !== 'object' \|\| Array.isArray(fmRaw)) {
3366	fmRaw = {};
3367	}
3368	let gatewayAirId = null;
3369	if (process.env.KNOWTATION_AIR_ENDPOINT) {
3370	try {
3371	const { attestBeforeWrite: gwAttest } = await import('../../lib/air.mjs');
3372	const airId = await gwAttest(
3373	{ air: { enabled: true, required: false, endpoint: process.env.KNOWTATION_AIR_ENDPOINT } },
3374	outPath,
3375	);
3376	if (airId && airId !== 'air-placeholder-write') {
3377	gatewayAirId = airId;
3378	}
3379	} catch (e) {
3380	console.error('[gateway] AIR attestation (copy, non-fatal):', e?.message \|\| String(e));
3381	}
3382	}
3383	const postBody = mergeHostedNoteBodyForCanister(
3384	{
3385	path: outPath,
3386	body: note.body != null ? String(note.body) : '',
3387	frontmatter: fmRaw,
3388	},
3389	uid,
3390	gatewayAirId,
3391	);
3392	const postHeaders = {
3393	'Content-Type': 'application/json',
3394	Accept: 'application/json',
3395	host: new URL(CANISTER_URL).host,
3396	'x-user-id': effective,
3397	'x-actor-id': uid,
3398	'x-vault-id': toVault,
3399	...canisterAuthHeaders(),
3400	};
3401	const postOpts = { method: 'POST', headers: postHeaders, body: JSON.stringify(postBody) };
3402	stripStaleOutboundBodyHeaders(postHeaders);
3403	let postUpstream;
3404	try {
3405	postUpstream = await fetch(`${CANISTER_URL}/api/v1/notes`, postOpts);
3406	} catch (e) {
3407	console.error('[gateway] notes/copy post target:', e?.message \|\| e);
3408	return res.status(502).json({ error: 'Bad Gateway', code: 'BAD_GATEWAY' });
3409	}
3410	const postText = await postUpstream.text();
3411	if (!postUpstream.ok) {
3412	return res.status(postUpstream.status).type('application/json').send(postText);
3413	}
3414	if (deleteSource) {
3415	let delUpstream;
3416	try {
3417	delUpstream = await fetch(getUrl, {
3418	method: 'DELETE',
3419	headers: {
3420	Accept: 'application/json',
3421	'x-user-id': effective,
3422	'x-actor-id': uid,
3423	'x-vault-id': fromVault,
3424	...canisterAuthHeaders(),
3425	},
3426	});
3427	} catch (e) {
3428	console.error('[gateway] notes/copy delete source:', e?.message \|\| e);
3429	return res.status(502).json({
3430	error:
3431	'Note was copied to the target vault but deleting the source failed. Remove the duplicate from the target vault if you retry.',
3432	code: 'DELETE_FAILED',
3433	});
3434	}
3435	const delText = await delUpstream.text();
3436	if (!delUpstream.ok && delUpstream.status !== 404) {
3437	return res.status(delUpstream.status).json({
3438	error: 'Note was copied to the target vault but deleting the source failed.',
3439	code: 'DELETE_FAILED',
3440	detail: typeof delText === 'string' ? delText.slice(0, 500) : '',
3441	});
3442	}
3443	}
3444	const reindexVaults = deleteSource ? [toVault, fromVault] : [toVault];
3445	void (async () => {
3446	if (!BRIDGE_URL) return;
3447	for (const vid of reindexVaults) {
3448	try {
3449	const idxRes = await fetch(BRIDGE_URL + '/api/v1/index', {
3450	method: 'POST',
3451	headers: {
3452	Authorization: authHeader,
3453	Accept: 'application/json',
3454	'Content-Type': 'application/json',
3455	'X-Vault-Id': String(vid \|\| 'default').trim() \|\| 'default',
3456	},
3457	body: '{}',
3458	});
3459	const idxText = await idxRes.text();
3460	await recordIndexingTokensAfterBridgeIndex(uid, idxRes.status, idxText);
3461	} catch (e) {
3462	console.warn('[gateway] notes/copy reindex:', e?.message \|\| e);
3463	}
3464	}
3465	})();
3466	res.set('Cache-Control', 'private, no-store, must-revalidate');
3467	return res.json({
3468	ok: true,
3469	path: outPath,
3470	from_vault_id: fromVault,
3471	to_vault_id: toVault,
3472	moved: deleteSource,
3473	});
3474	});
3475
3476	app.use('/api/v1', async (req, res) => {
3477	if (req.method === 'OPTIONS') return res.status(204).end();
3478	if (!(await runBillingGate(req, res, getUserId, { getNoteCount: getNoteCountForUser }))) return;
3479	return proxyToCanister(req, res);
3480	});
3481
3482	// Health from canister if UI calls /health via same origin
3483	app.get('/api/v1/health-canister', async (_req, res) => {
3484	try {
3485	const r = await fetch(CANISTER_URL + '/health');
3486	const body = await r.text();
3487	res.status(r.status).set('Content-Type', 'application/json').send(body);
3488	} catch (e) {
3489	res.status(502).json({ ok: false, error: e.message });
3490	}
3491	});
3492
3493	app.use((err, req, res, next) => {
3494	if (res.headersSent) return next(err);
3495	console.error('[gateway] unhandled error:', err?.stack \|\| err?.message \|\| err);
3496	const status =
3497	typeof err.status === 'number' && err.status >= 400 && err.status < 600
3498	? err.status
3499	: typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600
3500	? err.statusCode
3501	: 500;
3502	res.status(status).json({
3503	error: err.message \|\| 'Internal error',
3504	code: err.code \|\| 'INTERNAL_ERROR',
3505	});
3506	});
3507
3508	// When running on Netlify, the app is imported by netlify/functions/gateway.mjs and not started here.
3509	if (!process.env.NETLIFY) {
3510	if (!CANISTER_URL) {
3511	console.error('Gateway: CANISTER_URL is required (e.g. https://<canister-id>.ic0.app)');
3512	process.exit(1);
3513	}
3514	if (!SESSION_SECRET) {
3515	console.error('Gateway: SESSION_SECRET or HUB_JWT_SECRET is required');
3516	process.exit(1);
3517	}
3518	if (!CANISTER_AUTH_SECRET && CANISTER_URL) {
3519	console.warn(
3520	'\x1b[33m[SECURITY] CANISTER_AUTH_SECRET is not set. ' +
3521	'The canister will not verify gateway identity. ' +
3522	'Set CANISTER_AUTH_SECRET and call admin_set_gateway_auth_secret on the canister before public launch.\x1b[0m'
3523	);
3524	}
3525	if (CANISTER_URL && !billingEnforced()) {
3526	console.warn(
3527	'\x1b[33m[SECURITY] BILLING_ENFORCE is not set to true. ' +
3528	'Billing limits (storage cap, usage gates) are not enforced. ' +
3529	'Set BILLING_ENFORCE=true before public launch on hosted deployment.\x1b[0m'
3530	);
3531	}
3532	app.listen(PORT, () => {
3533	console.log(`Knowtation Hub Gateway listening on http://localhost:${PORT}`);
3534	console.log(' Canister: ' + CANISTER_URL);
3535	console.log(' UI origin: ' + HUB_UI_ORIGIN);
3536	console.log(' Login: GET /auth/login?provider=google\|github');
3537	});
3538	}
3539
3540	export { app };

File History 1 commit

sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 16 hours ago