@selvajs/server 0.2.0-beta.1 → 0.2.0-beta.3

package/src/errors/SentryErrorReporter.ts

@@ -0,0 +1,88 @@
+import type { ErrorContext, IErrorReporter } from '@selvajs/platform';
+
+/**
+ * `IErrorReporter` backed by Sentry (`@sentry/node`). Constructed only when
+ * the consuming app has a DSN configured. Deployments that don't configure a
+ * DSN never load `@sentry/node`, so it stays an OPTIONAL peer dependency: the
+ * base install ships without it and the no-op path needs no package at all.
+ *
+ * `@sentry/node` is imported dynamically and its surface is narrowed to the
+ * two calls we use — a hard static import would make the package mandatory.
+ */
+interface SentryLike {
+	init(options: {
+		dsn: string;
+		environment?: string;
+		release?: string;
+		tracesSampleRate: number;
+	}): void;
+	captureException(
+		error: unknown,
+		context?: {
+			tags?: Record<string, string>;
+			user?: { id?: string };
+			extra?: Record<string, unknown>;
+		}
+	): void;
+}
+
+export class SentryErrorReporter implements IErrorReporter {
+	private constructor(private readonly sentry: SentryLike) {}
+
+	/**
+	 * Initialize Sentry and return a reporter, or `null` if `@sentry/node` is
+	 * not installed (optional dependency absent). Never throws — a broken
+	 * error-tracker must not take down boot.
+	 */
+	static async create(opts: {
+		dsn: string;
+		environment?: string;
+		release?: string;
+	}): Promise<SentryErrorReporter | null> {
+		try {
+			// Dynamic so the package stays optional. `@vite-ignore` keeps the
+			// bundler from trying to resolve it at build time when it's absent.
+			// `@ts-ignore` (not `@ts-expect-error`) because whether the module
+			// resolves at type-check time depends on the environment — it's a real
+			// dep in some installs, absent in others — so we can't assert the error
+			// is always present. The `as unknown as` cast narrows whatever loads to
+			// the two calls we use.
+			// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+			// @ts-ignore -- optional dependency, may be absent at type-check time
+			const sentry = (await import(/* @vite-ignore */ '@sentry/node')) as unknown as SentryLike;
+			sentry.init({
+				dsn: opts.dsn,
+				environment: opts.environment,
+				release: opts.release,
+				// Error tracking only — no performance tracing by default. Flip
+				// this up later if you want transactions/spans.
+				tracesSampleRate: 0
+			});
+			return new SentryErrorReporter(sentry);
+		} catch (err) {
+			console.error(
+				'[ErrorReporter] A Sentry DSN is set but @sentry/node could not be loaded. ' +
+					'Install it (`pnpm add @sentry/node`) or unset the DSN. Falling back to no-op.',
+				err
+			);
+			return null;
+		}
+	}
+
+	capture(error: unknown, context?: ErrorContext): void {
+		try {
+			const tags: Record<string, string> = { ...context?.tags };
+			if (context?.method) tags.method = context.method;
+			if (context?.route) tags.route = context.route;
+			if (context?.orgId) tags.orgId = context.orgId;
+			this.sentry.captureException(error, {
+				tags,
+				user: context?.userId ? { id: context.userId } : undefined
+			});
+		} catch (err) {
+			// Reporting is best-effort and sits on the error path — a second
+			// failure here would mask the first. Swallow after logging.
+			console.error('[ErrorReporter] Failed to capture error:', err);
+		}
+	}
+}

package/src/errors/index.ts

@@ -0,0 +1,3 @@
+// Error reporting — Sentry-backed IErrorReporter (optional @sentry/node peer).
+
+export { SentryErrorReporter } from './SentryErrorReporter.js';

package/src/http/__tests__/body-size.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { declaredBodySizeExceeds } from '../body-size.js';
+
+function headersWith(contentLength?: string): Headers {
+	const h = new Headers();
+	if (contentLength !== undefined) h.set('content-length', contentLength);
+	return h;
+}
+
+describe('declaredBodySizeExceeds', () => {
+	it('flags a declared size over the limit', () => {
+		expect(declaredBodySizeExceeds(headersWith('1001'), 1000)).toBe(true);
+	});
+
+	it('passes a declared size at or under the limit', () => {
+		expect(declaredBodySizeExceeds(headersWith('1000'), 1000)).toBe(false);
+		expect(declaredBodySizeExceeds(headersWith('0'), 1000)).toBe(false);
+	});
+
+	it('passes when Content-Length is absent (chunked transfer — global limit is the backstop)', () => {
+		expect(declaredBodySizeExceeds(headersWith(), 1000)).toBe(false);
+	});
+
+	it('passes a non-numeric Content-Length rather than throwing', () => {
+		expect(declaredBodySizeExceeds(headersWith('not-a-number'), 1000)).toBe(false);
+	});
+});

package/src/http/__tests__/route-classifier.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { createRouteClassifier } from '../route-classifier.js';
+
+// Generic values — the consuming app's actual route policy is pinned by its
+// own test suite; these cover the classifier mechanics.
+const classifier = createRouteClassifier({
+	publicPages: ['/', '/login'],
+	publicPrefixes: ['/auth/', '/logout'],
+	publicApis: ['/api/health'],
+	selfGatingPrefix: '/api/files/',
+	staticPrefixes: ['/_app/', '/favicon/'],
+	staticPaths: ['/favicon.svg', '/robots.txt']
+});
+
+describe('createRouteClassifier', () => {
+	it('classifies exact pages, API allowlist, prefixes, and self-gating as public', () => {
+		for (const path of [
+			'/',
+			'/login',
+			'/api/health',
+			'/auth/oauth/callback',
+			'/logout',
+			'/api/files/orgs/abc/logo.webp'
+		]) {
+			expect(classifier.isPublicRoute(path)).toBe(true);
+		}
+	});
+
+	it('denies by default — unknown routes are gated', () => {
+		for (const path of ['/library', '/api/projects', '/billing', '/whatever']) {
+			expect(classifier.isPublicRoute(path)).toBe(false);
+		}
+	});
+
+	it('exact-match pages do not admit siblings via prefix', () => {
+		expect(classifier.isPublicRoute('/login-other')).toBe(false);
+		expect(classifier.isPublicRoute('/api/healthz')).toBe(false);
+	});
+
+	it('self-gating prefix is not a loose match', () => {
+		expect(classifier.isSelfGatingApiRoute('/api/files/x')).toBe(true);
+		expect(classifier.isSelfGatingApiRoute('/api/filesX/y')).toBe(false);
+		expect(classifier.isSelfGatingApiRoute('/api/projects')).toBe(false);
+	});
+
+	it('recognizes static assets by prefix and exact path', () => {
+		expect(classifier.isStaticAsset('/_app/immutable/x.js')).toBe(true);
+		expect(classifier.isStaticAsset('/favicon/16.png')).toBe(true);
+		expect(classifier.isStaticAsset('/robots.txt')).toBe(true);
+		expect(classifier.isStaticAsset('/favicon-other.png')).toBe(false);
+		expect(classifier.isStaticAsset('/login')).toBe(false);
+	});
+
+	it('every allowlist is optional — an empty config gates everything', () => {
+		const closed = createRouteClassifier({});
+		expect(closed.isPublicRoute('/')).toBe(false);
+		expect(closed.isStaticAsset('/robots.txt')).toBe(false);
+		expect(closed.isSelfGatingApiRoute('/api/files/x')).toBe(false);
+	});
+});

package/src/http/__tests__/safe-redirect.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { safeRedirectTarget } from '../redirect.js';
+
+/**
+ * `safeRedirectTarget` is the post-login redirect validator. The point of
+ * the function is to reject *exactly* the values that would otherwise
+ * smuggle an external host into a `redirect(303, …)` call:
+ * protocol-relative URLs (`//evil.com`) and back-slash variants some
+ * browsers normalize as a path separator. Each row below is one such case.
+ */
+describe('safeRedirectTarget', () => {
+	it.each([
+		['/foo', '/foo'],
+		['/foo/bar', '/foo/bar'],
+		['/foo?x=1', '/foo?x=1'],
+		['/foo#frag', '/foo#frag'],
+		['/a', '/a'] // shortest valid path: `/` + non-`/` char
+	])('accepts same-origin path %j → %j', (input, expected) => {
+		expect(safeRedirectTarget(input, '/fallback')).toBe(expected);
+	});
+
+	it.each([
+		['//evil.com', 'protocol-relative URL'],
+		['//evil.com/path', 'protocol-relative URL with path'],
+		['/\\evil.com', 'back-slash bypass'],
+		['https://evil.com', 'absolute URL'],
+		['http://evil.com', 'absolute URL'],
+		['javascript:alert(1)', 'javascript: scheme'],
+		['', 'empty string'],
+		['/', 'lone slash (length<2)'],
+		['evil.com', 'no leading slash'],
+		['./relative', 'relative path']
+	])('rejects %j (%s)', (input) => {
+		expect(safeRedirectTarget(input, '/fallback')).toBe('/fallback');
+	});
+
+	it.each([null, undefined])('rejects %j', (input) => {
+		expect(safeRedirectTarget(input, '/fallback')).toBe('/fallback');
+	});
+
+	it('passes through arbitrary non-string types as fallback', () => {
+		// safeRedirectTarget's signature is `string | null | undefined`, but
+		// some call sites get `unknown` from FormData — make sure we don't
+		// throw on a stray non-string.
+		expect(safeRedirectTarget(42 as unknown as string, '/fallback')).toBe('/fallback');
+	});
+});

package/src/http/__tests__/security-headers.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { applySecurityHeaders } from '../security-headers.js';
+
+describe('applySecurityHeaders', () => {
+	it('sets the baseline hardening headers and returns the same response', () => {
+		const response = new Response('ok');
+		const out = applySecurityHeaders(response, { hsts: false });
+		expect(out).toBe(response);
+		expect(out.headers.get('X-Content-Type-Options')).toBe('nosniff');
+		expect(out.headers.get('Referrer-Policy')).toBe('strict-origin-when-cross-origin');
+		expect(out.headers.get('Permissions-Policy')).toContain('camera=()');
+	});
+
+	it('sets HSTS only when asked (production)', () => {
+		const dev = applySecurityHeaders(new Response('ok'), { hsts: false });
+		expect(dev.headers.get('Strict-Transport-Security')).toBeNull();
+
+		const prod = applySecurityHeaders(new Response('ok'), { hsts: true });
+		expect(prod.headers.get('Strict-Transport-Security')).toBe(
+			'max-age=31536000; includeSubDomains'
+		);
+	});
+
+	it('never sets CSP or frame headers (iframe embedding is a product requirement)', () => {
+		const out = applySecurityHeaders(new Response('ok'), { hsts: true });
+		expect(out.headers.get('Content-Security-Policy')).toBeNull();
+		expect(out.headers.get('X-Frame-Options')).toBeNull();
+	});
+});

package/src/http/body-size.ts

@@ -0,0 +1,24 @@
+/** Minimal read-side view of a request's headers — `Headers` satisfies it. */
+export interface HeadersLike {
+	get(name: string): string | null;
+}
+
+/**
+ * True when the request's declared `Content-Length` exceeds `maxBytes`.
+ * Check BEFORE the body is read so a malicious client can't burn memory by
+ * sending a huge payload to a small-body endpoint; the route maps a `true`
+ * result to its transport's 413.
+ *
+ * Background: a global body-size limit (e.g. adapter-node's `BODY_SIZE_LIMIT`)
+ * has to be set high enough for the largest legitimate upload, which means
+ * smaller JSON endpoints inherit that ceiling by default. This check is the
+ * per-route lower bound.
+ *
+ * Caveat: requests without `Content-Length` (chunked transfer encoding) bypass
+ * this check. Most browsers and HTTP clients send Content-Length on POST/PUT.
+ * The global limit is the backstop for those.
+ */
+export function declaredBodySizeExceeds(headers: HeadersLike, maxBytes: number): boolean {
+	const declared = Number(headers.get('content-length'));
+	return Number.isFinite(declared) && declared > maxBytes;
+}

package/src/http/index.ts

@@ -0,0 +1,10 @@
+// HTTP hardening helpers — transport-agnostic request/response guards.
+
+export { safeRedirectTarget } from './redirect.js';
+export { declaredBodySizeExceeds, type HeadersLike } from './body-size.js';
+export { applySecurityHeaders, type SecurityHeaderOptions } from './security-headers.js';
+export {
+	createRouteClassifier,
+	type RouteClassifier,
+	type RouteClassifierConfig
+} from './route-classifier.js';

package/src/http/redirect.ts

@@ -0,0 +1,16 @@
+/**
+ * Validate a user-supplied post-login redirect target. Accepts only same-origin
+ * relative paths starting with `/` followed by a non-`/` character, so
+ * `//evil.com/path` (protocol-relative URL — browser treats as cross-origin)
+ * and `/\evil.com` (back-slash variants some browsers normalize) are rejected.
+ *
+ * Always returns a safe path: the validated target on success, the fallback
+ * otherwise. Routes call this with `redirectTo` from form data or query string.
+ */
+export function safeRedirectTarget(raw: string | null | undefined, fallback: string): string {
+	if (typeof raw !== 'string' || raw.length < 2) return fallback;
+	if (raw[0] !== '/') return fallback;
+	// Reject protocol-relative (`//host`) and back-slash bypass (`/\host`).
+	if (raw[1] === '/' || raw[1] === '\\') return fallback;
+	return raw;
+}

package/src/http/route-classifier.ts

@@ -0,0 +1,74 @@
+/**
+ * Deny-by-default route classification. Every request is gated unless its
+ * path matches one of the explicit allowlists supplied here — so adding a new
+ * top-level route is safe: forgetting to update the lists makes it gated (a
+ * loud 401/redirect), not silently public.
+ *
+ * The *pattern* is reusable; the *values* are app policy — a consuming app
+ * supplies its own route sets. All matching is plain exact/prefix string
+ * comparison: cheap enough for the hooks hot path, and no regex to get wrong.
+ */
+
+export interface RouteClassifierConfig {
+	/** Exact-match public pages — no session needed (e.g. `/`, `/login`). */
+	publicPages?: Iterable<string>;
+	/**
+	 * Public path prefixes (e.g. `/auth/` for OAuth start + callback — the
+	 * user has no session yet by definition).
+	 */
+	publicPrefixes?: readonly string[];
+	/**
+	 * Exact-match API endpoints that must answer without a session (e.g. a
+	 * load-balancer health probe). Anything added here must be safe to expose
+	 * to anonymous callers.
+	 */
+	publicApis?: Iterable<string>;
+	/**
+	 * A single prefix whose routes apply their own per-request authorization
+	 * (e.g. a blob proxy classifying each asset path). The hook must NOT deny
+	 * these up front; they classify as public (best-effort session attach) and
+	 * the route makes the real decision. Keep this to ONE prefix — every other
+	 * API route stays deny-by-default.
+	 */
+	selfGatingPrefix?: string;
+	/** Static-asset path prefixes the adapter serves directly (e.g. `/_app/`). */
+	staticPrefixes?: readonly string[];
+	/** Exact static-asset paths (e.g. `/favicon.svg`, `/robots.txt`). */
+	staticPaths?: Iterable<string>;
+}
+
+export interface RouteClassifier {
+	/** Static assets bypass auth gating; callers may add cache headers. */
+	isStaticAsset(pathname: string): boolean;
+	/** True for paths under `selfGatingPrefix` — the route gates itself. */
+	isSelfGatingApiRoute(pathname: string): boolean;
+	/** True when the path needs no session: pages, APIs, prefixes, self-gating. */
+	isPublicRoute(pathname: string): boolean;
+}
+
+export function createRouteClassifier(config: RouteClassifierConfig): RouteClassifier {
+	const publicPages = new Set(config.publicPages ?? []);
+	const publicPrefixes = config.publicPrefixes ?? [];
+	const publicApis = new Set(config.publicApis ?? []);
+	const selfGatingPrefix = config.selfGatingPrefix;
+	const staticPrefixes = config.staticPrefixes ?? [];
+	const staticPaths = new Set(config.staticPaths ?? []);
+
+	function isStaticAsset(pathname: string): boolean {
+		if (staticPaths.has(pathname)) return true;
+		return staticPrefixes.some((p) => pathname.startsWith(p));
+	}
+
+	function isSelfGatingApiRoute(pathname: string): boolean {
+		return selfGatingPrefix !== undefined && pathname.startsWith(selfGatingPrefix);
+	}
+
+	function isPublicRoute(pathname: string): boolean {
+		if (publicPages.has(pathname)) return true;
+		if (publicApis.has(pathname)) return true;
+		if (isSelfGatingApiRoute(pathname)) return true;
+		return publicPrefixes.some((p) => pathname.startsWith(p));
+	}
+
+	return { isStaticAsset, isSelfGatingApiRoute, isPublicRoute };
+}

package/src/http/security-headers.ts

@@ -0,0 +1,42 @@
+export interface SecurityHeaderOptions {
+	/**
+	 * Set `Strict-Transport-Security` — production only. Locking dev
+	 * (http://localhost) into HTTPS would brick local development, so the
+	 * caller decides what "production" means (e.g. `NODE_ENV`).
+	 */
+	hsts: boolean;
+}
+
+/**
+ * Apply baseline browser-hardening headers to a response. Cheap wins that
+ * don't require UI verification:
+ *
+ *   - X-Content-Type-Options: nosniff — disables MIME sniffing.
+ *   - Referrer-Policy: strict-origin-when-cross-origin — strips the path
+ *     and query from cross-origin Referer headers; matches modern browser
+ *     defaults but pins the behavior in case the default ever drifts.
+ *   - Permissions-Policy: opt out of browser APIs Selva-engine apps don't
+ *     use, so XSS can't enable them.
+ *   - HSTS when `opts.hsts` (production).
+ *
+ * **Intentionally NOT set here:**
+ *   - Content-Security-Policy + frame-ancestors. Selva-engine apps are built
+ *     for iframe embedding, so a strict CSP needs UI-phase validation against
+ *     real consumer sites before it can ship.
+ *   - X-Frame-Options. Same iframe-embedding constraint.
+ *   - Cache-Control. Asset-path layout is app policy; set it in the caller.
+ *
+ * Returns the same response for chaining.
+ */
+export function applySecurityHeaders(response: Response, opts: SecurityHeaderOptions): Response {
+	response.headers.set('X-Content-Type-Options', 'nosniff');
+	response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+	response.headers.set(
+		'Permissions-Policy',
+		'accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()'
+	);
+	if (opts.hsts) {
+		response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+	}
+	return response;
+}

package/src/index.ts

@@ -9,10 +9,19 @@
  *
  * The full compute subsurface is also available at `@selvajs/server/compute`,
  * the definitions slice (DefinitionService, schema extraction/validation,
- * render loader) at `@selvajs/server/definitions`, and the provider wiring
- * (registry-driven `createSelvaProviders`) at `@selvajs/server/providers`.
+ * render loader) at `@selvajs/server/definitions`, the provider wiring
+ * (registry-driven `createSelvaProviders`) at `@selvajs/server/providers`,
+ * the HMAC token codec at `@selvajs/server/tokens`, error reporting at
+ * `@selvajs/server/errors`, HTTP hardening helpers at `@selvajs/server/http`,
+ * access-rule input assembly at `@selvajs/server/access`, and deployment/ops
+ * helpers at `@selvajs/server/ops`.
  */
 
 export * from './compute/index.js';
 export * from './definitions/index.js';
 export * from './providers/index.js';
+export * from './tokens/index.js';
+export * from './errors/index.js';
+export * from './http/index.js';
+export * from './access/index.js';
+export * from './ops/index.js';

package/src/ops/__tests__/semver.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { isNewer } from '../semver.js';
+
+describe('isNewer', () => {
+	it('detects a newer patch / minor / major', () => {
+		expect(isNewer('4.3.2', '4.3.1')).toBe(true);
+		expect(isNewer('4.4.0', '4.3.9')).toBe(true);
+		expect(isNewer('5.0.0', '4.9.9')).toBe(true);
+	});
+
+	it('returns false for same or older versions', () => {
+		expect(isNewer('4.3.1', '4.3.1')).toBe(false);
+		expect(isNewer('4.3.0', '4.3.1')).toBe(false);
+		expect(isNewer('3.9.9', '4.0.0')).toBe(false);
+	});
+
+	it('ignores pre-release suffixes on the stable channel (only stable bumps surface)', () => {
+		expect(isNewer('4.3.2-beta.1', '4.3.1')).toBe(true);
+		expect(isNewer('4.3.1-beta.1', '4.3.1')).toBe(false);
+		// Explicit stable channel matches the default.
+		expect(isNewer('4.3.1-beta.1', '4.3.1', 'stable')).toBe(false);
+	});
+
+	it('orders pre-releases on the beta channel', () => {
+		// Successive betas of the same core.
+		expect(isNewer('4.6.0-beta.2', '4.6.0-beta.1', 'beta')).toBe(true);
+		expect(isNewer('4.6.0-beta.1', '4.6.0-beta.2', 'beta')).toBe(false);
+		// A newer core beta beats an older stable.
+		expect(isNewer('4.6.0-beta.1', '4.5.1', 'beta')).toBe(true);
+		// Stable of a core outranks any beta of the same core (promotion).
+		expect(isNewer('4.6.0', '4.6.0-beta.9', 'beta')).toBe(true);
+		expect(isNewer('4.6.0-beta.9', '4.6.0', 'beta')).toBe(false);
+		// Reverting to an OLDER stable is NOT "newer" — the channel switch, not
+		// isNewer, is what makes it actionable.
+		expect(isNewer('4.5.1', '4.6.0-beta.2', 'beta')).toBe(false);
+	});
+
+	it('falls back to a string compare when unparseable', () => {
+		expect(isNewer('weird', 'weird')).toBe(false);
+		expect(isNewer('a', 'b')).toBe(true);
+	});
+});

package/src/ops/index.ts

@@ -0,0 +1,3 @@
+// Deployment/ops helpers — channel-aware semver comparison.
+
+export { parseSemver, isNewer, type ReleaseChannel } from './semver.js';

package/src/ops/semver.ts

@@ -0,0 +1,60 @@
+/**
+ * Channel-aware semver comparison for update checks. Understands exactly the
+ * two-channel model Selva-engine deployments publish under: a stable line
+ * (`x.y.z`, npm `latest`) and a beta line (`x.y.z-beta.N`, npm `beta`).
+ * Deliberately not a general semver implementation — no build metadata, no
+ * arbitrary pre-release identifiers.
+ */
+
+/** Which published line a deployment tracks. */
+export type ReleaseChannel = 'stable' | 'beta';
+
+/**
+ * Parse `x.y.z` plus an optional `-beta.N` pre-release counter. The
+ * pre-release number is returned separately so beta-channel comparisons can
+ * order successive betas of the same x.y.z core. Returns null for anything
+ * that doesn't lead with a numeric core.
+ */
+export function parseSemver(
+	v: string
+): { core: [number, number, number]; beta: number | null } | null {
+	const m = /^(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?/.exec(v.trim());
+	if (!m) return null;
+	return {
+		core: [Number(m[1]), Number(m[2]), Number(m[3])],
+		beta: m[4] != null ? Number(m[4]) : null
+	};
+}
+
+/**
+ * True when `latest` is strictly newer than `current` by semver.
+ *
+ * Stable channel (default): pre-release suffixes are ignored — only stable
+ * core bumps surface.
+ *
+ * Beta channel: pre-releases participate. A higher core wins; on an equal
+ * core, a higher `-beta.N` wins, and a stable (no suffix) outranks any -beta
+ * of the same core (4.6.0 > 4.6.0-beta.9). This lets an update UI show
+ * "beta.1 → beta.2" and "beta → stable promotion of the same line".
+ *
+ * Unparseable versions fall back to inequality: different strings count as
+ * "newer" so a weird published version still surfaces, identical ones don't.
+ */
+export function isNewer(
+	latest: string,
+	current: string,
+	channel: ReleaseChannel = 'stable'
+): boolean {
+	const a = parseSemver(latest);
+	const b = parseSemver(current);
+	if (!a || !b) return latest !== current;
+	for (let i = 0; i < 3; i++) {
+		if (a.core[i] > b.core[i]) return true;
+		if (a.core[i] < b.core[i]) return false;
+	}
+	// Equal core. On the stable channel we don't compare pre-release tails.
+	if (channel !== 'beta') return false;
+	// Stable (beta == null) ranks above any pre-release of the same core.
+	const rank = (beta: number | null) => (beta == null ? Infinity : beta);
+	return rank(a.beta) > rank(b.beta);
+}

package/src/tokens/__tests__/token-codec.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { createTokenCodec, MIN_TOKEN_SECRET_LENGTH } from '../token-codec.js';
+
+const SECRET = 'unit-test-secret-that-is-long-enough-to-pass';
+
+describe('createTokenCodec', () => {
+	it('rejects a secret shorter than the minimum', () => {
+		expect(() => createTokenCodec({ prefix: 'share_', secret: 'short' })).toThrow(
+			/at least 32 characters/
+		);
+		expect(() =>
+			createTokenCodec({ prefix: 'share_', secret: 'x'.repeat(MIN_TOKEN_SECRET_LENGTH - 1) })
+		).toThrow(/got 31/);
+	});
+
+	it('accepts a secret at exactly the minimum length', () => {
+		expect(() =>
+			createTokenCodec({ prefix: 'share_', secret: 'x'.repeat(MIN_TOKEN_SECRET_LENGTH) })
+		).not.toThrow();
+	});
+
+	it('mints prefixed, unique, URL-safe tokens', () => {
+		const codec = createTokenCodec({ prefix: 'share_', secret: SECRET });
+		const a = codec.mintRawToken();
+		const b = codec.mintRawToken();
+		expect(a).toMatch(/^share_[A-Za-z0-9_-]{43}$/); // 32 bytes → 43 base64url chars
+		expect(a).not.toBe(b);
+	});
+
+	it('hashes deterministically, never echoing the raw token', () => {
+		const codec = createTokenCodec({ prefix: 'share_', secret: SECRET });
+		const raw = codec.mintRawToken();
+		const hash = codec.hashToken(raw);
+		expect(codec.hashToken(raw)).toBe(hash);
+		expect(hash).not.toContain(raw);
+		expect(hash).toMatch(/^[A-Za-z0-9_-]+$/); // base64url
+	});
+
+	it('produces different hashes under different secrets (rotation invalidates)', () => {
+		const a = createTokenCodec({ prefix: 'share_', secret: SECRET });
+		const b = createTokenCodec({ prefix: 'share_', secret: SECRET + '-rotated' });
+		const raw = a.mintRawToken();
+		expect(a.hashToken(raw)).not.toBe(b.hashToken(raw));
+	});
+
+	it('hashesEqual: equal, unequal, and length-mismatch inputs', () => {
+		const codec = createTokenCodec({ prefix: 'invite_', secret: SECRET });
+		const hash = codec.hashToken(codec.mintRawToken());
+		const other = codec.hashToken(codec.mintRawToken());
+		expect(codec.hashesEqual(hash, hash)).toBe(true);
+		expect(codec.hashesEqual(hash, other)).toBe(false);
+		expect(codec.hashesEqual(hash, hash.slice(0, -1))).toBe(false);
+	});
+
+	it('looksLikeToken recognizes only its own prefix', () => {
+		const share = createTokenCodec({ prefix: 'share_', secret: SECRET });
+		const invite = createTokenCodec({ prefix: 'invite_', secret: SECRET });
+		const raw = share.mintRawToken();
+		expect(share.looksLikeToken(raw)).toBe(true);
+		expect(invite.looksLikeToken(raw)).toBe(false);
+		expect(share.looksLikeToken('random-string')).toBe(false);
+	});
+});

package/src/tokens/index.ts

@@ -0,0 +1,8 @@
+// HMAC token codec for capability-URL tokens (share links, invites, …).
+
+export {
+	createTokenCodec,
+	MIN_TOKEN_SECRET_LENGTH,
+	type TokenCodec,
+	type TokenCodecConfig
+} from './token-codec.js';