@xopcai/xopc 0.0.231 → 0.0.232

package/dist/src/notifications/device-store.js

@@ -41,11 +41,11 @@ function deviceFromRow(row) {
 }
 function registerNotificationDevice(input) {
 	const now = Date.now();
-	const preferences = input.preferences ? normalizePreferences(input.preferences) : getNotificationDevice(input.id)?.preferences ?? normalizePreferences();
+	const preferences = input.preferences ? normalizePreferences(input.preferences) : getNotificationDevice(input.deviceId)?.preferences ?? normalizePreferences();
 	runSqliteWriteTransaction((db) => {
-		db.prepare(`DELETE FROM notification_devices
-       WHERE push_provider = 'expo' AND push_token = ? AND device_id <> ?`).run(input.pushToken, input.id);
-		db.prepare(`INSERT INTO notification_devices (
+		db.prepare(`DELETE FROM device_push_endpoints
+       WHERE push_token = ? AND device_id <> ?`).run(input.pushToken, input.deviceId);
+		db.prepare(`INSERT INTO device_push_endpoints (
         device_id, platform, push_token, enabled, permissions, preferences_json,
         locale, app_version, lease_expires_at, last_seen_at, created_at, updated_at
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
@@ -59,16 +59,16 @@ function registerNotificationDevice(input) {
         app_version = excluded.app_version,
         lease_expires_at = excluded.lease_expires_at,
         last_seen_at = excluded.last_seen_at,
-        updated_at = excluded.updated_at`).run(input.id, input.platform, input.pushToken, input.permissions === "granted" ? 1 : 0, input.permissions, JSON.stringify(preferences), input.locale, input.appVersion?.trim() || null, now + DEVICE_LEASE_MS, now, now, now);
+        updated_at = excluded.updated_at`).run(input.deviceId, input.platform, input.pushToken, input.permissions === "granted" ? 1 : 0, input.permissions, JSON.stringify(preferences), input.locale, input.appVersion?.trim() || null, now + DEVICE_LEASE_MS, now, now, now);
 	});
-	return getNotificationDevice(input.id);
+	return getNotificationDevice(input.deviceId);
 }
 function getNotificationDevice(deviceId) {
-	const row = getSqliteDatabase().prepare("SELECT * FROM notification_devices WHERE device_id = ?").get(deviceId);
+	const row = getSqliteDatabase().prepare("SELECT * FROM device_push_endpoints WHERE device_id = ?").get(deviceId);
 	return row ? deviceFromRow(row) : null;
 }
 function listDeliverableNotificationDevices(now = Date.now()) {
-	return getSqliteDatabase().prepare(`SELECT * FROM notification_devices
+	return getSqliteDatabase().prepare(`SELECT * FROM device_push_endpoints
      WHERE enabled = 1 AND permissions = 'granted' AND lease_expires_at > ?
      ORDER BY updated_at DESC`).all(now).map(deviceFromRow);
 }
@@ -80,16 +80,16 @@ function updateNotificationDevicePreferences(deviceId, patch) {
 		...patch
 	});
 	runSqliteWriteTransaction((db) => {
-		db.prepare("UPDATE notification_devices SET preferences_json = ?, updated_at = ? WHERE device_id = ?").run(JSON.stringify(preferences), Date.now(), deviceId);
+		db.prepare("UPDATE device_push_endpoints SET preferences_json = ?, updated_at = ? WHERE device_id = ?").run(JSON.stringify(preferences), Date.now(), deviceId);
 	});
 	return getNotificationDevice(deviceId);
 }
 function removeNotificationDevice(deviceId) {
-	return runSqliteWriteTransaction((db) => db.prepare("DELETE FROM notification_devices WHERE device_id = ?").run(deviceId).changes > 0);
+	return runSqliteWriteTransaction((db) => db.prepare("DELETE FROM device_push_endpoints WHERE device_id = ?").run(deviceId).changes > 0);
 }
 function disableNotificationDeviceForPushToken(pushToken) {
 	runSqliteWriteTransaction((db) => {
-		db.prepare("UPDATE notification_devices SET enabled = 0, updated_at = ? WHERE push_token = ?").run(Date.now(), pushToken);
+		db.prepare("UPDATE device_push_endpoints SET enabled = 0, updated_at = ? WHERE push_token = ?").run(Date.now(), pushToken);
 	});
 }
 //#endregion

package/dist/src/notifications/store.js

@@ -88,7 +88,7 @@ const DELIVERY_JOIN = `
          n.push_token, n.locale
   FROM notification_deliveries d
   JOIN notification_events e ON e.event_id = d.event_id
-  JOIN notification_devices n ON n.device_id = d.device_id
+  JOIN device_push_endpoints n ON n.device_id = d.device_id
 `;
 function listDueNotificationDeliveries(status, now = Date.now(), limit = 100) {
 	return getSqliteDatabase().prepare(`${DELIVERY_JOIN}
@@ -135,7 +135,7 @@ function notificationDeliveryMetrics() {
        SUM(CASE WHEN enabled = 1 AND permissions = 'granted' AND lease_expires_at > ? THEN 1 ELSE 0 END) AS deliverable,
        SUM(CASE WHEN enabled = 1 AND lease_expires_at <= ? THEN 1 ELSE 0 END) AS expired,
        SUM(CASE WHEN enabled = 0 OR permissions <> 'granted' THEN 1 ELSE 0 END) AS disabled
-     FROM notification_devices`).get(now, now);
+     FROM device_push_endpoints`).get(now, now);
 	const oldest = getSqliteDatabase().prepare(`SELECT MIN(next_attempt_at) AS value FROM notification_deliveries
      WHERE status IN ('pending', 'accepted')`).get();
 	const latestError = getSqliteDatabase().prepare(`SELECT event_id, device_id, last_error, updated_at
@@ -166,7 +166,7 @@ function expireUndeliverableNotificationDeliveries(now = Date.now()) {
      SET status = 'dead', last_error = 'Device registration is disabled or expired', updated_at = ?
      WHERE status IN ('pending', 'accepted')
        AND EXISTS (
-         SELECT 1 FROM notification_devices n
+         SELECT 1 FROM device_push_endpoints n
          WHERE n.device_id = notification_deliveries.device_id
            AND (n.enabled = 0 OR n.permissions <> 'granted' OR n.lease_expires_at <= ?)
        )`).run(now, now).changes));

package/dist/src/providers/index.js

@@ -90,7 +90,7 @@ function getApiKeySync(provider) {
 */
 function resolveModel(ref) {
 	const trimmedRef = typeof ref === "string" ? ref.trim() : "";
-	if (!trimmedRef) throw new Error("No default model configured. Choose a model in onboarding or set agents.capabilityPresets.default.models.roles.<role>.model.");
+	if (!trimmedRef) throw new Error("No default model configured. Choose a model in onboarding or set agents.defaults.models.chat.primary.");
 	const customModel = getModelRegistry().resolve(trimmedRef);
 	if (customModel) return normalizeProviderModel(customModel);
 	const qualifiedRef = splitProviderModelRef(trimmedRef);

package/dist/src/providers/model-reference-auditor.js

@@ -24,19 +24,24 @@ function collectToolModel(out, value, location, kind = "text") {
 function collectModelPolicy(out, value, location) {
 	const policy = asRecord(value);
 	if (!policy) return;
-	const roles = asRecord(policy.roles);
-	for (const [roleId, roleValue] of Object.entries(roles ?? {})) {
-		const role = asRecord(roleValue);
-		if (!role) continue;
-		addRef(out, role.model, `${location}.roles.${roleId}.model`);
-		if (Array.isArray(role.fallbacks)) role.fallbacks.forEach((ref, index) => addRef(out, ref, `${location}.roles.${roleId}.fallbacks[${index}]`));
+	const chat = asRecord(policy.chat);
+	if (chat) {
+		addRef(out, chat.primary, `${location}.chat.primary`);
+		if (Array.isArray(chat.fallbacks)) chat.fallbacks.forEach((ref, index) => addRef(out, ref, `${location}.chat.fallbacks[${index}]`));
 	}
-	collectToolModel(out, policy.imageModel, `${location}.imageModel`);
-	collectToolModel(out, policy.imageGenerationModel, `${location}.imageGenerationModel`, "image-generation");
+	const intents = asRecord(policy.intents);
+	for (const [intent, routeValue] of Object.entries(intents ?? {})) {
+		const route = asRecord(routeValue);
+		if (!route) continue;
+		addRef(out, route.primary, `${location}.intents.${intent}.primary`);
+		if (Array.isArray(route.fallbacks)) route.fallbacks.forEach((ref, index) => addRef(out, ref, `${location}.intents.${intent}.fallbacks[${index}]`));
+	}
+	collectToolModel(out, policy.imageUnderstanding, `${location}.imageUnderstanding`);
+	collectToolModel(out, policy.imageGeneration, `${location}.imageGeneration`, "image-generation");
 }
 function collectReferences(config, sessionConfigs) {
 	const out = [];
-	for (const [presetId, preset] of Object.entries(config.agents.capabilityPresets)) collectModelPolicy(out, preset.models, `agents.capabilityPresets.${presetId}.models`);
+	collectModelPolicy(out, config.agents.defaults.models, "agents.defaults.models");
 	for (const agent of config.agents.list) collectModelPolicy(out, agent.models, `agents.list.${agent.id}.models`);
 	for (const [sessionKey, sessionConfig] of sessionConfigs) addRef(out, sessionConfig.modelOverride, `sessions.${sessionKey}.modelOverride`);
 	return out;

package/dist/src/realtime/runtime.d.ts

@@ -10,10 +10,12 @@ export declare class RealtimeRuntime {
     private readonly preauthBudget;
     private readonly wss;
     private readonly topicCleanupTimers;
+    private readonly socketsByPrincipal;
     private closed;
     constructor(endpointTools?: EndpointToolRuntime);
     handleUpgrade(req: IncomingMessage, socket: Socket, head: Buffer): boolean;
     close(): void;
+    disconnectPrincipal(principalId: string): void;
     completeTopic(topic: string, ttlMs?: number): void;
     private handleConnection;
     private rawDataToText;

package/dist/src/realtime/runtime.js

@@ -1,5 +1,6 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
+import { hasGatewayScope } from "../gateway/security/gateway-scopes.js";
 import { REALTIME_HEARTBEAT_INTERVAL_MS, REALTIME_HEARTBEAT_TIMEOUT_MS, REALTIME_HELLO_TIMEOUT_MS, REALTIME_MAX_CLIENT_FRAME_BYTES, parseClientRealtimeJsonFrame, parseClientRealtimeMessage } from "../../packages/realtime-protocol/src/index.js";
 import { createPreauthConnectionBudget } from "../gateway/security/preauth-connection-budget.js";
 import { RealtimeBroker } from "./broker.js";
@@ -24,8 +25,13 @@ function serverMessage(kind, payload) {
 		payload
 	};
 }
-function isAuthorizedTopic(topic) {
-	return topic === "gateway" || topic === "sessions" || topic === "logs" || topic.startsWith("session:") && topic.length > 8 || topic.startsWith("run:") && topic.length > 4 || topic.startsWith("workflow:") && topic.length > 9;
+function isAuthorizedTopic(topic, scopes) {
+	if (topic === "gateway") return hasGatewayScope(scopes, "gateway.status");
+	if (topic === "logs") return hasGatewayScope(scopes, "gateway.admin");
+	if (topic === "sessions" || topic.startsWith("session:")) return hasGatewayScope(scopes, "sessions.read");
+	if (topic.startsWith("run:")) return hasGatewayScope(scopes, "agents.run");
+	if (topic.startsWith("workflow:")) return hasGatewayScope(scopes, "automations.read");
+	return false;
 }
 var RealtimeRuntime = class {
 	broker = new RealtimeBroker(void 0, (error, topic) => {
@@ -42,6 +48,7 @@ var RealtimeRuntime = class {
 		perMessageDeflate: false
 	});
 	topicCleanupTimers = /* @__PURE__ */ new Map();
+	socketsByPrincipal = /* @__PURE__ */ new Map();
 	closed = false;
 	constructor(endpointTools) {
 		this.endpointTools = endpointTools;
@@ -80,6 +87,10 @@ var RealtimeRuntime = class {
 		for (const timer of this.topicCleanupTimers.values()) clearTimeout(timer);
 		this.topicCleanupTimers.clear();
 		this.wss.close();
+		this.socketsByPrincipal.clear();
+	}
+	disconnectPrincipal(principalId) {
+		for (const socket of this.socketsByPrincipal.get(principalId) ?? []) socket.close(4403, "Device access revoked");
 	}
 	completeTopic(topic, ttlMs = 5 * 6e4) {
 		const existing = this.topicCleanupTimers.get(topic);
@@ -97,6 +108,8 @@ var RealtimeRuntime = class {
 		let lastSeenAt = Date.now();
 		let connectionId;
 		let endpointId;
+		let principalId;
+		let grantedScopes = [];
 		let budgetHeld = true;
 		const releaseBudget = () => {
 			if (!budgetHeld) return;
@@ -115,7 +128,7 @@ var RealtimeRuntime = class {
 		};
 		const subscribe = (requested) => {
 			const authorized = requested.filter((item) => {
-				if (isAuthorizedTopic(item.topic)) return true;
+				if (isAuthorizedTopic(item.topic, grantedScopes)) return true;
 				sendError("FORBIDDEN_TOPIC", `Topic is not available: ${item.topic}`);
 				return false;
 			});
@@ -172,6 +185,11 @@ var RealtimeRuntime = class {
 					return;
 				}
 				authenticated = true;
+				principalId = claim.principalId;
+				grantedScopes = claim.scopes;
+				const principalSockets = this.socketsByPrincipal.get(principalId) ?? /* @__PURE__ */ new Set();
+				principalSockets.add(socket);
+				this.socketsByPrincipal.set(principalId, principalSockets);
 				connectionId = crypto.randomUUID();
 				let endpointReady;
 				if (message.payload.endpoint) {
@@ -215,6 +233,7 @@ var RealtimeRuntime = class {
 				subscribe(message.payload.subscriptions);
 				log.info({
 					connectionId,
+					principalId,
 					clientId: claim.clientId,
 					clientKind: claim.clientKind
 				}, "Realtime client connected");
@@ -249,6 +268,11 @@ var RealtimeRuntime = class {
 			for (const handle of subscriptions.values()) handle.unsubscribe();
 			subscriptions.clear();
 			if (endpointId && connectionId) this.endpointTools?.remove(endpointId, connectionId);
+			if (principalId) {
+				const principalSockets = this.socketsByPrincipal.get(principalId);
+				principalSockets?.delete(socket);
+				if (principalSockets?.size === 0) this.socketsByPrincipal.delete(principalId);
+			}
 			if (connectionId) {
 				const reason = reasonBuffer.toString();
 				log.info({

package/dist/src/realtime/tickets.d.ts

@@ -1,7 +1,12 @@
 import type { RealtimeClientKind } from '@xopcai/realtime-protocol';
+import type { GatewayScope } from '../gateway/security/gateway-scopes.js';
 export interface RealtimeTicketClaim {
     clientId: string;
     clientKind: RealtimeClientKind;
+    principalId: string;
+    deviceId?: string;
+    accessSessionId?: string;
+    scopes: readonly GatewayScope[];
     expiresAt: number;
 }
 export interface IssuedRealtimeTicket extends RealtimeTicketClaim {
@@ -9,7 +14,7 @@ export interface IssuedRealtimeTicket extends RealtimeTicketClaim {
 }
 export declare class RealtimeTicketStore {
     private readonly claims;
-    issue(clientId: string, clientKind: RealtimeClientKind, now?: number): IssuedRealtimeTicket;
+    issue(clientId: string, clientKind: RealtimeClientKind, principal: Omit<RealtimeTicketClaim, 'clientId' | 'clientKind' | 'expiresAt'>, now?: number): IssuedRealtimeTicket;
     consume(ticket: string, clientId: string, clientKind: RealtimeClientKind, now?: number): RealtimeTicketClaim | undefined;
     private prune;
 }

package/dist/src/realtime/tickets.js

@@ -7,13 +7,14 @@ function ticketKey(ticket) {
 }
 var RealtimeTicketStore = class {
 	claims = /* @__PURE__ */ new Map();
-	issue(clientId, clientKind, now = Date.now()) {
+	issue(clientId, clientKind, principal, now = Date.now()) {
 		this.prune(now);
 		if (this.claims.size >= MAX_OUTSTANDING_TICKETS) throw new Error("Too many outstanding realtime tickets");
 		const ticket = crypto.randomBytes(32).toString("base64url");
 		const claim = {
 			clientId,
 			clientKind,
+			...principal,
 			expiresAt: now + TICKET_TTL_MS
 		};
 		this.claims.set(ticketKey(ticket), claim);

package/dist/src/remote-access/exposure-manager.js

@@ -2,11 +2,11 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { isTailscaleInstalled } from "../infra/tailscale.js";
 import { resolveGatewayBindMode } from "../config/gateway-bind.js";
-import { getTunnelConsentState } from "../tunnel/consent.js";
-import { getTunnelService } from "../tunnel/tunnel-service.js";
-import { maybeAutoStartTunnelFromConfig } from "../tunnel/gateway-lifecycle.js";
 import { collectExposureConflicts } from "./exposure-guards.js";
 import { getTailscaleExposureState, maybeStartTailscaleFromConfig, stopTailscaleExposure } from "../gateway/tailscale-lifecycle.js";
+import { getTunnelService } from "../tunnel/tunnel-service.js";
+import { getTunnelConsentState } from "../tunnel/consent.js";
+import { maybeAutoStartTunnelFromConfig } from "../tunnel/gateway-lifecycle.js";
 //#region src/remote-access/exposure-manager.ts
 init_logger();
 const log = createLogger("ExposureManager");

package/dist/src/share/share-url.js

@@ -1,5 +1,5 @@
+import { enumerateLanGatewayCandidates } from "../gateway/host.js";
 import { loadTunnelState } from "../tunnel/tunnel-state.js";
-import { resolveLanGatewayUrl } from "../tunnel/tunnel-qr.js";
 //#region src/share/share-url.ts
 function resolveShareUrl(token, ctx) {
 	const tunnelState = loadTunnelState();
@@ -32,7 +32,7 @@ function resolveShareUrl(token, ctx) {
 	};
 }
 function buildLanUrl(host, port, path) {
-	const lanBase = resolveLanGatewayUrl(host, port);
+	const lanBase = isLoopbackHost(host) ? null : enumerateLanGatewayCandidates(port).find((candidate) => candidate.address === host)?.url ?? `http://${host.includes(":") ? `[${host}]` : host}:${port}`;
 	if (!lanBase) return null;
 	return `${lanBase.replace(/\/+$/, "")}${path}`;
 }

package/dist/src/storage/sqlite/device-access-repository.d.ts

@@ -0,0 +1,54 @@
+import crypto from 'node:crypto';
+import type { GatewayScope } from '../../gateway/security/gateway-scopes.js';
+export type DevicePlatform = 'ios' | 'android';
+export type DevicePublicKeyJwk = crypto.webcrypto.JsonWebKey;
+export type DeviceRecord = {
+    id: string;
+    displayName: string;
+    platform: DevicePlatform;
+    publicKeyJwk: DevicePublicKeyJwk;
+    scopes: GatewayScope[];
+    createdAt: number;
+    lastSeenAt?: number;
+    revokedAt?: number;
+};
+export type DeviceAccessIdentity = {
+    deviceId: string;
+    accessSessionId: string;
+    scopes: GatewayScope[];
+};
+export type DeviceTokenPair = {
+    accessToken: string;
+    accessTokenExpiresAt: number;
+    refreshToken: string;
+    refreshTokenExpiresAt: number;
+};
+export declare function createDevice(input: {
+    id?: string;
+    displayName: string;
+    platform: DevicePlatform;
+    publicKeyJwk: DevicePublicKeyJwk;
+    scopes: readonly GatewayScope[];
+    now?: number;
+}): DeviceRecord;
+export declare function getDevice(deviceId: string): DeviceRecord | undefined;
+export declare function listDevices(): DeviceRecord[];
+export declare function issueDeviceTokenPair(deviceId: string, now?: number): DeviceTokenPair;
+export declare function authenticateDeviceAccessToken(token: string, now?: number): DeviceAccessIdentity | undefined;
+export declare function buildRefreshProofMessage(input: {
+    credentialId: string;
+    timestamp: number;
+    nonce: string;
+    requestId: string;
+    nextRefreshToken: string;
+}): string;
+export declare function rotateDeviceRefreshToken(input: {
+    refreshToken: string;
+    timestamp: number;
+    nonce: string;
+    requestId: string;
+    nextRefreshToken: string;
+    signature: string;
+    now?: number;
+}): DeviceTokenPair;
+export declare function revokeDevice(deviceId: string, now?: number): boolean;

package/dist/src/storage/sqlite/device-access-repository.js

@@ -0,0 +1,194 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import { parseGatewayScopes } from "../../gateway/security/gateway-scopes.js";
+import crypto from "node:crypto";
+//#region src/storage/sqlite/device-access-repository.ts
+const ACCESS_TOKEN_TTL_MS = 900 * 1e3;
+const REFRESH_TOKEN_TTL_MS = 2160 * 60 * 60 * 1e3;
+const REFRESH_PROOF_MAX_AGE_MS = 300 * 1e3;
+const ACCESS_TOKEN_PREFIX = "xopc_at_";
+const REFRESH_TOKEN_PREFIX = "xopc_rt_";
+function tokenHash(token) {
+	return crypto.createHash("sha256").update(token).digest("hex");
+}
+function buildToken(prefix, id) {
+	return `${prefix}${id}_${crypto.randomBytes(32).toString("base64url")}`;
+}
+function parseToken(token, prefix) {
+	if (!token.startsWith(prefix)) return void 0;
+	const separator = token.indexOf("_", prefix.length);
+	if (separator <= prefix.length || separator === token.length - 1) return void 0;
+	return { id: token.slice(prefix.length, separator) };
+}
+function deviceFromRow(row) {
+	return {
+		id: row.device_id,
+		displayName: row.display_name,
+		platform: row.platform,
+		publicKeyJwk: JSON.parse(row.public_key_jwk),
+		scopes: parseGatewayScopes(row.scopes_json),
+		createdAt: row.created_at,
+		...row.last_seen_at === null ? {} : { lastSeenAt: row.last_seen_at },
+		...row.revoked_at === null ? {} : { revokedAt: row.revoked_at }
+	};
+}
+function createDevice(input) {
+	const id = input.id ?? crypto.randomUUID();
+	const createdAt = input.now ?? Date.now();
+	getSqliteDatabase().prepare(`
+    INSERT INTO devices (
+      device_id, display_name, platform, public_key_jwk, scopes_json, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?)
+  `).run(id, input.displayName, input.platform, JSON.stringify(input.publicKeyJwk), JSON.stringify([...new Set(input.scopes)]), createdAt);
+	return getDevice(id);
+}
+function getDevice(deviceId) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM devices WHERE device_id = ?").get(deviceId);
+	return row ? deviceFromRow(row) : void 0;
+}
+function listDevices() {
+	return getSqliteDatabase().prepare("SELECT * FROM devices ORDER BY created_at DESC").all().map(deviceFromRow);
+}
+function issueAccessToken(deviceId, now) {
+	const accessSessionId = crypto.randomUUID();
+	const accessToken = buildToken(ACCESS_TOKEN_PREFIX, accessSessionId);
+	const accessTokenExpiresAt = now + ACCESS_TOKEN_TTL_MS;
+	getSqliteDatabase().prepare(`
+    INSERT INTO device_access_sessions (
+      session_id, device_id, token_hash, expires_at, created_at
+    ) VALUES (?, ?, ?, ?, ?)
+  `).run(accessSessionId, deviceId, tokenHash(accessToken), accessTokenExpiresAt, now);
+	return {
+		accessToken,
+		accessTokenExpiresAt
+	};
+}
+function issueDeviceTokenPair(deviceId, now = Date.now()) {
+	const device = getDevice(deviceId);
+	if (!device || device.revokedAt !== void 0) throw new Error("Device is unavailable");
+	const refreshCredentialId = crypto.randomUUID();
+	const refreshToken = buildToken(REFRESH_TOKEN_PREFIX, refreshCredentialId);
+	const refreshTokenExpiresAt = now + REFRESH_TOKEN_TTL_MS;
+	return {
+		...runSqliteWriteTransaction((db) => {
+			const issuedAccess = issueAccessToken(deviceId, now);
+			db.prepare(`
+      INSERT INTO device_refresh_credentials (
+        credential_id, device_id, token_hash, expires_at, created_at
+      ) VALUES (?, ?, ?, ?, ?)
+    `).run(refreshCredentialId, deviceId, tokenHash(refreshToken), refreshTokenExpiresAt, now);
+			return issuedAccess;
+		}),
+		refreshToken,
+		refreshTokenExpiresAt
+	};
+}
+function authenticateDeviceAccessToken(token, now = Date.now()) {
+	const parsed = parseToken(token, ACCESS_TOKEN_PREFIX);
+	if (!parsed) return void 0;
+	const row = getSqliteDatabase().prepare(`
+    SELECT a.session_id, a.device_id, a.token_hash, a.expires_at, a.revoked_at,
+           d.scopes_json, d.revoked_at AS device_revoked_at
+    FROM device_access_sessions a
+    JOIN devices d ON d.device_id = a.device_id
+    WHERE a.session_id = ?
+  `).get(parsed.id);
+	if (!row || row.expires_at <= now || row.revoked_at !== null || row.device_revoked_at !== null || !crypto.timingSafeEqual(Buffer.from(row.token_hash, "hex"), Buffer.from(tokenHash(token), "hex"))) return;
+	getSqliteDatabase().prepare("UPDATE devices SET last_seen_at = ? WHERE device_id = ?").run(now, row.device_id);
+	return {
+		deviceId: row.device_id,
+		accessSessionId: row.session_id,
+		scopes: parseGatewayScopes(row.scopes_json)
+	};
+}
+function buildRefreshProofMessage(input) {
+	return `xopc-device-refresh-v2\n${input.credentialId}\n${input.timestamp}\n${input.nonce}\n${input.requestId}\n${input.nextRefreshToken}`;
+}
+function verifyRefreshProof(publicKeyJwk, message, signature) {
+	try {
+		const publicKey = crypto.createPublicKey({
+			key: publicKeyJwk,
+			format: "jwk"
+		});
+		return crypto.verify("sha256", Buffer.from(message), {
+			key: publicKey,
+			dsaEncoding: "ieee-p1363"
+		}, Buffer.from(signature, "base64url"));
+	} catch {
+		return false;
+	}
+}
+function rotateDeviceRefreshToken(input) {
+	const now = input.now ?? Date.now();
+	const parsed = parseToken(input.refreshToken, REFRESH_TOKEN_PREFIX);
+	const nextParsed = parseToken(input.nextRefreshToken, REFRESH_TOKEN_PREFIX);
+	if (!parsed || !nextParsed || parsed.id === nextParsed.id) throw new Error("Invalid refresh credential");
+	if (Math.abs(now - input.timestamp) > REFRESH_PROOF_MAX_AGE_MS) throw new Error("Refresh proof expired");
+	const result = runSqliteWriteTransaction((db) => {
+		const credential = db.prepare(`
+      SELECT credential_id, device_id, token_hash, expires_at, replaced_by,
+             rotation_request_id, revoked_at
+      FROM device_refresh_credentials WHERE credential_id = ?
+    `).get(parsed.id);
+		const suppliedHash = tokenHash(input.refreshToken);
+		if (!credential || credential.token_hash !== suppliedHash) throw new Error("Invalid refresh credential");
+		const deviceRow = db.prepare("SELECT * FROM devices WHERE device_id = ?").get(credential.device_id);
+		if (!deviceRow || deviceRow.revoked_at !== null) throw new Error("Device is unavailable");
+		const message = buildRefreshProofMessage({
+			credentialId: credential.credential_id,
+			timestamp: input.timestamp,
+			nonce: input.nonce,
+			requestId: input.requestId,
+			nextRefreshToken: input.nextRefreshToken
+		});
+		if (!verifyRefreshProof(JSON.parse(deviceRow.public_key_jwk), message, input.signature)) throw new Error("Invalid refresh proof");
+		if (credential.replaced_by === nextParsed.id && credential.rotation_request_id === input.requestId) {
+			const nextCredential = db.prepare(`
+        SELECT credential_id, device_id, token_hash, expires_at, replaced_by,
+               rotation_request_id, revoked_at
+        FROM device_refresh_credentials WHERE credential_id = ?
+      `).get(nextParsed.id);
+			if (nextCredential?.token_hash === tokenHash(input.nextRefreshToken)) return {
+				...issueAccessToken(credential.device_id, now),
+				refreshToken: input.nextRefreshToken,
+				refreshTokenExpiresAt: nextCredential.expires_at
+			};
+		}
+		if (credential.replaced_by !== null || credential.revoked_at !== null) {
+			db.prepare("UPDATE devices SET revoked_at = ? WHERE device_id = ? AND revoked_at IS NULL").run(now, credential.device_id);
+			db.prepare("UPDATE device_access_sessions SET revoked_at = ? WHERE device_id = ? AND revoked_at IS NULL").run(now, credential.device_id);
+			db.prepare("UPDATE device_refresh_credentials SET revoked_at = ? WHERE device_id = ? AND revoked_at IS NULL").run(now, credential.device_id);
+			return "reused";
+		}
+		if (credential.expires_at <= now) throw new Error("Refresh credential expired");
+		const access = issueAccessToken(credential.device_id, now);
+		const refreshTokenExpiresAt = now + REFRESH_TOKEN_TTL_MS;
+		db.prepare(`
+      INSERT INTO device_refresh_credentials (
+        credential_id, device_id, token_hash, expires_at, created_at
+      ) VALUES (?, ?, ?, ?, ?)
+    `).run(nextParsed.id, credential.device_id, tokenHash(input.nextRefreshToken), refreshTokenExpiresAt, now);
+		db.prepare(`
+      UPDATE device_refresh_credentials
+      SET last_used_at = ?, replaced_by = ?, rotation_request_id = ?, revoked_at = ?
+      WHERE credential_id = ?
+    `).run(now, nextParsed.id, input.requestId, now, credential.credential_id);
+		return {
+			...access,
+			refreshToken: input.nextRefreshToken,
+			refreshTokenExpiresAt
+		};
+	});
+	if (result === "reused") throw new Error("Refresh credential reuse detected");
+	return result;
+}
+function revokeDevice(deviceId, now = Date.now()) {
+	return runSqliteWriteTransaction((db) => {
+		const changed = db.prepare("UPDATE devices SET revoked_at = ? WHERE device_id = ? AND revoked_at IS NULL").run(now, deviceId).changes > 0;
+		db.prepare("UPDATE device_access_sessions SET revoked_at = ? WHERE device_id = ? AND revoked_at IS NULL").run(now, deviceId);
+		db.prepare("UPDATE device_refresh_credentials SET revoked_at = ? WHERE device_id = ? AND revoked_at IS NULL").run(now, deviceId);
+		db.prepare("DELETE FROM device_push_endpoints WHERE device_id = ?").run(deviceId);
+		return changed;
+	});
+}
+//#endregion
+export { authenticateDeviceAccessToken, buildRefreshProofMessage, createDevice, getDevice, issueDeviceTokenPair, listDevices, revokeDevice, rotateDeviceRefreshToken };

package/dist/src/storage/sqlite/device-pairing-repository.d.ts

@@ -0,0 +1,22 @@
+export type DeviceRoute = {
+    id: string;
+    kind: 'xopc-secure-link' | 'tailscale' | 'custom-https';
+    url: string;
+};
+export type DevicePairingSetup = {
+    id: string;
+    token: string;
+    routes: DeviceRoute[];
+    expiresAt: number;
+};
+export type PairingConsumeResult = {
+    ok: true;
+    pairingId: string;
+    routes: DeviceRoute[];
+} | {
+    ok: false;
+    reason: 'invalid' | 'expired' | 'consumed';
+};
+export declare function createDevicePairingSetup(routes: readonly DeviceRoute[], now?: number): DevicePairingSetup;
+export declare function consumeDevicePairingToken(token: string, now?: number): PairingConsumeResult;
+export declare function isDevicePairingSetupActive(pairingId: string, now?: number): boolean;

package/dist/src/storage/sqlite/device-pairing-repository.js

@@ -0,0 +1,86 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import crypto from "node:crypto";
+//#region src/storage/sqlite/device-pairing-repository.ts
+const PAIRING_TOKEN_PREFIX = "xopc_pair_";
+const PAIRING_TTL_MS = 600 * 1e3;
+const PAIRING_ATTEMPTS = 5;
+function hashToken(token) {
+	return crypto.createHash("sha256").update(token).digest("hex");
+}
+function hashesMatch(left, right) {
+	return crypto.timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
+}
+function tokenId(token) {
+	if (!token.startsWith(PAIRING_TOKEN_PREFIX)) return void 0;
+	const separator = token.indexOf("_", 10);
+	if (separator <= 10 || separator === token.length - 1) return void 0;
+	return token.slice(10, separator);
+}
+function createDevicePairingSetup(routes, now = Date.now()) {
+	if (routes.length === 0) throw new Error("No secure mobile route is available");
+	const id = crypto.randomUUID();
+	const token = `${PAIRING_TOKEN_PREFIX}${id}_${crypto.randomBytes(32).toString("base64url")}`;
+	const expiresAt = now + PAIRING_TTL_MS;
+	runSqliteWriteTransaction((db) => {
+		db.prepare("DELETE FROM device_pairing_sessions WHERE expires_at <= ? OR consumed_at IS NOT NULL").run(now);
+		db.prepare(`
+      INSERT INTO device_pairing_sessions (
+        pairing_id, secret_hash, routes_json, expires_at, attempts_remaining, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?)
+    `).run(id, hashToken(token), JSON.stringify(routes), expiresAt, PAIRING_ATTEMPTS, now);
+	});
+	return {
+		id,
+		token,
+		routes: [...routes],
+		expiresAt
+	};
+}
+function consumeDevicePairingToken(token, now = Date.now()) {
+	const id = tokenId(token);
+	if (!id) return {
+		ok: false,
+		reason: "invalid"
+	};
+	return runSqliteWriteTransaction((db) => {
+		const row = db.prepare("SELECT * FROM device_pairing_sessions WHERE pairing_id = ?").get(id);
+		if (!row || row.attempts_remaining <= 0) return {
+			ok: false,
+			reason: "invalid"
+		};
+		if (row.consumed_at !== null) return {
+			ok: false,
+			reason: "consumed"
+		};
+		if (row.expires_at <= now) return {
+			ok: false,
+			reason: "expired"
+		};
+		if (!hashesMatch(row.secret_hash, hashToken(token))) {
+			db.prepare(`
+        UPDATE device_pairing_sessions
+        SET attempts_remaining = attempts_remaining - 1
+        WHERE pairing_id = ? AND attempts_remaining > 0
+      `).run(id);
+			return {
+				ok: false,
+				reason: "invalid"
+			};
+		}
+		db.prepare("UPDATE device_pairing_sessions SET consumed_at = ? WHERE pairing_id = ?").run(now, id);
+		return {
+			ok: true,
+			pairingId: id,
+			routes: JSON.parse(row.routes_json)
+		};
+	});
+}
+function isDevicePairingSetupActive(pairingId, now = Date.now()) {
+	const row = getSqliteDatabase().prepare(`
+    SELECT 1 FROM device_pairing_sessions
+    WHERE pairing_id = ? AND expires_at > ? AND consumed_at IS NULL AND attempts_remaining > 0
+  `).get(pairingId, now);
+	return Boolean(row);
+}
+//#endregion
+export { consumeDevicePairingToken, createDevicePairingSetup, isDevicePairingSetupActive };