@xopcai/xopc 0.0.231 → 0.0.233

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 };

package/dist/src/storage/sqlite/endpoint-session-binding-repository.d.ts

@@ -0,0 +1,8 @@
+export interface StoredEndpointSessionBinding {
+    sessionKey: string;
+    endpointId: string;
+    boundAt: number;
+}
+export declare function getEndpointSessionBinding(sessionKey: string): StoredEndpointSessionBinding | undefined;
+export declare function setEndpointSessionBinding(binding: StoredEndpointSessionBinding): StoredEndpointSessionBinding;
+export declare function deleteEndpointSessionBinding(sessionKey: string): boolean;

package/dist/src/storage/sqlite/endpoint-session-binding-repository.js

@@ -0,0 +1,32 @@
+import { getSqliteDatabase } from "./transaction.js";
+//#region src/storage/sqlite/endpoint-session-binding-repository.ts
+function fromRow(row) {
+	return {
+		sessionKey: row.session_key,
+		endpointId: row.endpoint_id,
+		boundAt: row.bound_at
+	};
+}
+function getEndpointSessionBinding(sessionKey) {
+	const row = getSqliteDatabase().prepare(`
+    SELECT session_key, endpoint_id, bound_at
+    FROM endpoint_session_bindings
+    WHERE session_key = ?
+  `).get(sessionKey);
+	return row ? fromRow(row) : void 0;
+}
+function setEndpointSessionBinding(binding) {
+	getSqliteDatabase().prepare(`
+    INSERT INTO endpoint_session_bindings (session_key, endpoint_id, bound_at)
+    VALUES (?, ?, ?)
+    ON CONFLICT(session_key) DO UPDATE SET
+      endpoint_id = excluded.endpoint_id,
+      bound_at = excluded.bound_at
+  `).run(binding.sessionKey, binding.endpointId, binding.boundAt);
+	return binding;
+}
+function deleteEndpointSessionBinding(sessionKey) {
+	return getSqliteDatabase().prepare("DELETE FROM endpoint_session_bindings WHERE session_key = ?").run(sessionKey).changes > 0;
+}
+//#endregion
+export { deleteEndpointSessionBinding, getEndpointSessionBinding, setEndpointSessionBinding };

package/dist/src/storage/sqlite/gateway-identity-repository.d.ts

@@ -0,0 +1,10 @@
+export type GatewayIdentity = {
+    id: string;
+    publicKey: string;
+    privateKey: string;
+    createdAt: number;
+};
+export declare function getOrCreateGatewayIdentity(now?: number): GatewayIdentity;
+export declare function signGatewayPayload(payload: string): string;
+export declare function getGatewayIdentityPublicKeyRaw(identity?: GatewayIdentity): string;
+export declare function clearGatewayIdentityForTest(): void;

package/dist/src/storage/sqlite/gateway-identity-repository.js

@@ -0,0 +1,50 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import crypto from "node:crypto";
+//#region src/storage/sqlite/gateway-identity-repository.ts
+function fromRow(row) {
+	return {
+		id: row.gateway_id,
+		publicKey: row.public_key,
+		privateKey: row.private_key,
+		createdAt: row.created_at
+	};
+}
+function getOrCreateGatewayIdentity(now = Date.now()) {
+	return runSqliteWriteTransaction((db) => {
+		const existing = db.prepare("SELECT * FROM gateway_identity WHERE singleton_id = 1").get();
+		if (existing) return fromRow(existing);
+		const keys = crypto.generateKeyPairSync("ed25519");
+		const identity = {
+			id: crypto.randomUUID(),
+			publicKey: keys.publicKey.export({
+				type: "spki",
+				format: "pem"
+			}).toString(),
+			privateKey: keys.privateKey.export({
+				type: "pkcs8",
+				format: "pem"
+			}).toString(),
+			createdAt: now
+		};
+		db.prepare(`
+      INSERT INTO gateway_identity (
+        singleton_id, gateway_id, public_key, private_key, created_at
+      ) VALUES (1, ?, ?, ?, ?)
+    `).run(identity.id, identity.publicKey, identity.privateKey, identity.createdAt);
+		return identity;
+	});
+}
+function signGatewayPayload(payload) {
+	const identity = getOrCreateGatewayIdentity();
+	return crypto.sign(null, Buffer.from(payload), identity.privateKey).toString("base64url");
+}
+function getGatewayIdentityPublicKeyRaw(identity = getOrCreateGatewayIdentity()) {
+	const jwk = crypto.createPublicKey(identity.publicKey).export({ format: "jwk" });
+	if (typeof jwk.x !== "string") throw new Error("Gateway identity public key is invalid");
+	return jwk.x;
+}
+function clearGatewayIdentityForTest() {
+	getSqliteDatabase().prepare("DELETE FROM gateway_identity").run();
+}
+//#endregion
+export { clearGatewayIdentityForTest, getGatewayIdentityPublicKeyRaw, getOrCreateGatewayIdentity, signGatewayPayload };

package/dist/src/storage/sqlite/index.d.ts

@@ -5,6 +5,10 @@ export { DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError, } from './m
 export { discoverSqlMigrations, listRegisteredMigrationTargets } from './migrations/discover.js';
 export { closeXopcDatabase, getXopcDatabase, isXopcDatabaseOpen, openXopcDatabase, requireXopcDatabase, resetXopcDatabaseSingletonForTest, type OpenXopcDatabaseOptions, type XopcDatabase, } from './connection.js';
 export { getSqliteDatabase, runSqliteWriteTransaction } from './transaction.js';
+export { deleteEndpointSessionBinding, getEndpointSessionBinding, setEndpointSessionBinding, type StoredEndpointSessionBinding, } from './endpoint-session-binding-repository.js';
+export { authenticateDeviceAccessToken, buildRefreshProofMessage, createDevice, getDevice, issueDeviceTokenPair, listDevices, revokeDevice, rotateDeviceRefreshToken, type DeviceAccessIdentity, type DevicePlatform, type DevicePublicKeyJwk, type DeviceRecord, type DeviceTokenPair, } from './device-access-repository.js';
+export { clearGatewayIdentityForTest, getOrCreateGatewayIdentity, signGatewayPayload, type GatewayIdentity, } from './gateway-identity-repository.js';
+export { consumeDevicePairingToken, createDevicePairingSetup, isDevicePairingSetupActive, type DevicePairingSetup, type DeviceRoute, type PairingConsumeResult, } from './device-pairing-repository.js';
 export { claimContextExtractionRun, finishContextExtractionRun, getContextExtractionRun, hasIndependentExtractionOutput, listContextExtractionOutputs, listContextExtractionRuns, type ContextExtractionOutput, type ContextExtractionRun, type ContextExtractionStatus, type ContextObjectType, } from './context-extraction-repository.js';
 export { closeTemporalAssertions, createTemporalAssertion, linkContextObjects, listContextObjectRelations, listTemporalAssertions, type ContextObjectRelation, type ContextTemporalAssertion, } from './context-relation-repository.js';
 export { finishContextConsolidationRun, getContextConsolidationRun, listContextConsolidationDecisions, listContextConsolidationRuns, recordContextConsolidationDecision, startContextConsolidationRun, type ContextConsolidationDecision, type ContextConsolidationRun, } from './context-consolidation-repository.js';

package/dist/src/storage/sqlite/index.js

@@ -6,6 +6,10 @@ import { XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_SCHEMA_VERSION, applyPendingMi
 import { ensureXopcDatabaseSchema } from "./schema.js";
 import { closeXopcDatabase, getXopcDatabase, isXopcDatabaseOpen, openXopcDatabase, requireXopcDatabase, resetXopcDatabaseSingletonForTest } from "./connection.js";
 import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import { deleteEndpointSessionBinding, getEndpointSessionBinding, setEndpointSessionBinding } from "./endpoint-session-binding-repository.js";
+import { authenticateDeviceAccessToken, buildRefreshProofMessage, createDevice, getDevice, issueDeviceTokenPair, listDevices, revokeDevice, rotateDeviceRefreshToken } from "./device-access-repository.js";
+import { clearGatewayIdentityForTest, getOrCreateGatewayIdentity, signGatewayPayload } from "./gateway-identity-repository.js";
+import { consumeDevicePairingToken, createDevicePairingSetup, isDevicePairingSetupActive } from "./device-pairing-repository.js";
 import { claimContextExtractionRun, finishContextExtractionRun, getContextExtractionRun, hasIndependentExtractionOutput, listContextExtractionOutputs, listContextExtractionRuns } from "./context-extraction-repository.js";
 import { closeTemporalAssertions, createTemporalAssertion, linkContextObjects, listContextObjectRelations, listTemporalAssertions } from "./context-relation-repository.js";
 import { finishContextConsolidationRun, getContextConsolidationRun, listContextConsolidationDecisions, listContextConsolidationRuns, recordContextConsolidationDecision, startContextConsolidationRun } from "./context-consolidation-repository.js";
@@ -36,4 +40,4 @@ import { appendConnectorExecutionAudit, claimConnectorWebhookDelivery, completeC
 import { getConnectorAccount, listConnectorAccounts, reconcileConnectorAccount, refreshConnectorAccountCurrent } from "./connector-account-repository.js";
 import { getConnectorSyncPolicy, getConnectorSyncPolicyForConnection, listConnectorSyncPolicies, upsertConnectorSyncPolicy } from "./connector-sync-policy-repository.js";
 import { getUserTrustPolicy, setUserTrustPolicy } from "./user-trust-repository.js";
-export { COMPOSER_INPUT_HISTORY_LIMIT, DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError, SCHEMA_META_SCHEMA_VERSION_KEY, XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_FILENAME, XOPC_DB_SCHEMA_VERSION, acknowledgeHomeAttention, appendCompactionBoundaryIfUnchanged, appendComposerInputHistory, appendConnectorExecutionAudit, appendMemorySignal, appendMemoryTraceEvent, appendTranscriptEntry, applyPendingMigrations, attachMemoryEvidence, bindEndpointPrincipal, buildDefaultSessionMetadata, buildGlobalSessionStats, buildRelationshipPrompt, cancelQueuedSessionInput, claimConnectorWebhookDelivery, claimContextExtractionRun, claimKnowledgeSourceItems, claimNextConnectorLearningJob, claimNextSessionInput, classifyStoredRow, clearComposerInputHistory, closeTemporalAssertions, closeUnderstandingValidity, closeXopcDatabase, completeConnectorWebhookDelivery, completeKnowledgeSourceItemSynthesis, consumeConnectorApproval, consumeContextConsent, countKnowledgeSourceItems, countMemoryRecordsBySourceInstanceId, createCollaborationRule, createConnectorApproval, createContextEvidence, createEndpointPrincipal, createObjectLinkRecord, createTemporalAssertion, createUnderstanding, decideConnectorApproval, decideContextConsent, deleteCollaborationRule, deleteConnectorConnection, deleteConnectorInstallation, deleteKnowledgeSourceItems, deleteMemoryEvidenceForRecord, deleteMemoryRecord, deleteMemoryRecordsBySourceInstanceId, deleteNoteAgentContextRecord, deleteNoteRecord, deleteObjectLinkRecord, deleteSessionConfig, deleteSessionRecord, deleteUnderstanding, discoverSqlMigrations, enqueueConnectorLearningJob, ensureContextConsent, ensureSessionRecord, ensureXopcDatabaseSchema, estimateTokensFromMessages, extractFtsContent, findSessionInput, findSessionKeyBySessionId, finishContextConsolidationRun, finishContextExtractionRun, finishEndpointToolInvocationAudit, finishKnowledgeSyncRun, finishSessionInputRun, getActivityEventRecord, getCachedConnectorCatalogEntry, getCollaborationRule, getConnectorAccount, getConnectorApproval, getConnectorConnection, getConnectorInstallation, getConnectorSyncPolicy, getConnectorSyncPolicyForConnection, getContextConsolidationRun, getContextExtractionRun, getCurrentSessionId, getEndpointPrincipal, getGlobalSessionStats, getInteractionState, getKnowledgeConsumerWatermark, getKnowledgeSourceCursor, getKnowledgeSourceItem, getMemoryProviderState, getMemoryRecord, getMemoryTurnFeedback, getNoteAgentContextRecord, getNoteRecord, getRelationshipSettings, getSessionConfig, getSessionInputById, getSessionInputState, getSessionMetadata, getSessionPersistedLevels, getSessionTaskPlan, getSqliteDatabase, getTurnPersonalization, getUnderstanding, getUserPeopleIndexState, getUserPerson, getUserProfile, getUserTrustPolicy, getXopcDatabase, hasContextConsent, hasIndependentExtractionOutput, hasSessionConfig, hasUnresolvedMemoryConflict, incrementSessionStatsOnAppend, insertSessionInput, inspectSchemaMigrationStatus, isHomeAttentionAcknowledged, isProactiveSupportAllowed, isUnderstandingSuppressed, isXopcDatabaseOpen, linkContextObjects, linkUnderstandingEvidence, listActiveSessionInputRuns, listActivityRecords, listCachedConnectorCatalogEntries, listCollaborationRules, listCompactionBoundaries, listComposerInputHistory, listConnectorAccounts, listConnectorActionMetadata, listConnectorApprovals, listConnectorConnections, listConnectorExecutionAudit, listConnectorInstallations, listConnectorLearningJobs, listConnectorSyncPolicies, listContextConsolidationDecisions, listContextConsolidationRuns, listContextExtractionOutputs, listContextExtractionRuns, listContextObjectRelations, listEndpointPrincipals, listEndpointToolInvocationAudits, listKnowledgeSourceChanges, listKnowledgeSourceItems, listKnowledgeSyncRuns, listMemoryEvidence, listMemoryRecords, listMemorySignals, listMemoryTraceEvents, listNoteRecords, listObjectActivityRecords, listObjectLinkRecords, listProjectActivityRecords, listRegisteredMigrationTargets, listSessionMetadata, listSessionsByAgent, listTemporalAssertions, listUnderstandingEvidence, listUnderstandingStatusEvents, listUnderstandings, listUserPeople, loadCompactionSourceSnapshot, loadLlmMessagesForSession, loadTranscriptHistoryRowsForSession, loadTranscriptRows, loadTranscriptRowsForSession, markMemoryRecordsConflicted, mergeUserPeople, metadataToSessionInsert, mutateQueuedSessionInput, openXopcDatabase, paginateTranscriptMessages, patchSessionMetadata, pruneBoundedKnowledgeSourceItems, readSchemaVersion, readSchemaVersionForTest, reconcileConnectorAccount, recordActivityEvent, recordContextConsolidationDecision, recordContextFeedback, recordContextRun, recoverSessionInputState, recoverStaleConnectorLearningJobs, refreshConnectorAccountCurrent, rejectUnderstanding, releaseConnectorWebhookDelivery, replaceConnectorCatalogEntries, replaceLatestSessionTurnAndQueueInput, replaceTranscriptRows, replaceUserPeopleIndex, requireXopcDatabase, resetSessionRecord, resetXopcDatabaseSingletonForTest, resolveMigrationsDir, resolveSessionAgentId, resolveXopcDatabasePath, restoreBeforeCompactionBoundary, reviseCollaborationRule, reviseUnderstanding, revokeEndpointPrincipal, runSqliteWriteTransaction, searchActiveUnderstandings, searchMemoryRecords, searchSessionTranscript, sessionConfigRowToConfig, sessionRowToMetadata, setCollaborationRuleStatus, setConnectorLearningPaused, setInteractionState, setKnowledgeConsumerWatermark, setKnowledgeSourceCursor, setKnowledgeSourceItemSynthesisStatus, setMemoryProviderState, setMemoryRecordStatus, setMemoryTurnFeedback, setSessionConfig, setSessionInputStatus, setSessionTaskPlan, setUnderstandingStatus, setUserTrustPolicy, startContextConsolidationRun, startEndpointToolInvocationAudit, startKnowledgeSyncRun, summarizeMemoryRecallFeedback, summarizeUnderstandingFeedback, summarizeUserPeople, summarizeUserUnderstandingQuality, touchEndpointPrincipal, transcriptEntryRowToStoredRow, updateConnectorLearningJob, updateInteractionStateFromMessage, updateRelationshipSettings, updateSessionConfig, updateSessionStats, updateUserPerson, updateUserProfile, upsertConnectorActionMetadata, upsertConnectorCatalogEntry, upsertConnectorConnection, upsertConnectorInstallation, upsertConnectorSyncPolicy, upsertKnowledgeSourceItems, upsertMemoryRecord, upsertNoteAgentContextRecord, upsertNoteRecord, validateLatestSessionTurnTarget };
+export { COMPOSER_INPUT_HISTORY_LIMIT, DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError, SCHEMA_META_SCHEMA_VERSION_KEY, XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_FILENAME, XOPC_DB_SCHEMA_VERSION, acknowledgeHomeAttention, appendCompactionBoundaryIfUnchanged, appendComposerInputHistory, appendConnectorExecutionAudit, appendMemorySignal, appendMemoryTraceEvent, appendTranscriptEntry, applyPendingMigrations, attachMemoryEvidence, authenticateDeviceAccessToken, bindEndpointPrincipal, buildDefaultSessionMetadata, buildGlobalSessionStats, buildRefreshProofMessage, buildRelationshipPrompt, cancelQueuedSessionInput, claimConnectorWebhookDelivery, claimContextExtractionRun, claimKnowledgeSourceItems, claimNextConnectorLearningJob, claimNextSessionInput, classifyStoredRow, clearComposerInputHistory, clearGatewayIdentityForTest, closeTemporalAssertions, closeUnderstandingValidity, closeXopcDatabase, completeConnectorWebhookDelivery, completeKnowledgeSourceItemSynthesis, consumeConnectorApproval, consumeContextConsent, consumeDevicePairingToken, countKnowledgeSourceItems, countMemoryRecordsBySourceInstanceId, createCollaborationRule, createConnectorApproval, createContextEvidence, createDevice, createDevicePairingSetup, createEndpointPrincipal, createObjectLinkRecord, createTemporalAssertion, createUnderstanding, decideConnectorApproval, decideContextConsent, deleteCollaborationRule, deleteConnectorConnection, deleteConnectorInstallation, deleteEndpointSessionBinding, deleteKnowledgeSourceItems, deleteMemoryEvidenceForRecord, deleteMemoryRecord, deleteMemoryRecordsBySourceInstanceId, deleteNoteAgentContextRecord, deleteNoteRecord, deleteObjectLinkRecord, deleteSessionConfig, deleteSessionRecord, deleteUnderstanding, discoverSqlMigrations, enqueueConnectorLearningJob, ensureContextConsent, ensureSessionRecord, ensureXopcDatabaseSchema, estimateTokensFromMessages, extractFtsContent, findSessionInput, findSessionKeyBySessionId, finishContextConsolidationRun, finishContextExtractionRun, finishEndpointToolInvocationAudit, finishKnowledgeSyncRun, finishSessionInputRun, getActivityEventRecord, getCachedConnectorCatalogEntry, getCollaborationRule, getConnectorAccount, getConnectorApproval, getConnectorConnection, getConnectorInstallation, getConnectorSyncPolicy, getConnectorSyncPolicyForConnection, getContextConsolidationRun, getContextExtractionRun, getCurrentSessionId, getDevice, getEndpointPrincipal, getEndpointSessionBinding, getGlobalSessionStats, getInteractionState, getKnowledgeConsumerWatermark, getKnowledgeSourceCursor, getKnowledgeSourceItem, getMemoryProviderState, getMemoryRecord, getMemoryTurnFeedback, getNoteAgentContextRecord, getNoteRecord, getOrCreateGatewayIdentity, getRelationshipSettings, getSessionConfig, getSessionInputById, getSessionInputState, getSessionMetadata, getSessionPersistedLevels, getSessionTaskPlan, getSqliteDatabase, getTurnPersonalization, getUnderstanding, getUserPeopleIndexState, getUserPerson, getUserProfile, getUserTrustPolicy, getXopcDatabase, hasContextConsent, hasIndependentExtractionOutput, hasSessionConfig, hasUnresolvedMemoryConflict, incrementSessionStatsOnAppend, insertSessionInput, inspectSchemaMigrationStatus, isDevicePairingSetupActive, isHomeAttentionAcknowledged, isProactiveSupportAllowed, isUnderstandingSuppressed, isXopcDatabaseOpen, issueDeviceTokenPair, linkContextObjects, linkUnderstandingEvidence, listActiveSessionInputRuns, listActivityRecords, listCachedConnectorCatalogEntries, listCollaborationRules, listCompactionBoundaries, listComposerInputHistory, listConnectorAccounts, listConnectorActionMetadata, listConnectorApprovals, listConnectorConnections, listConnectorExecutionAudit, listConnectorInstallations, listConnectorLearningJobs, listConnectorSyncPolicies, listContextConsolidationDecisions, listContextConsolidationRuns, listContextExtractionOutputs, listContextExtractionRuns, listContextObjectRelations, listDevices, listEndpointPrincipals, listEndpointToolInvocationAudits, listKnowledgeSourceChanges, listKnowledgeSourceItems, listKnowledgeSyncRuns, listMemoryEvidence, listMemoryRecords, listMemorySignals, listMemoryTraceEvents, listNoteRecords, listObjectActivityRecords, listObjectLinkRecords, listProjectActivityRecords, listRegisteredMigrationTargets, listSessionMetadata, listSessionsByAgent, listTemporalAssertions, listUnderstandingEvidence, listUnderstandingStatusEvents, listUnderstandings, listUserPeople, loadCompactionSourceSnapshot, loadLlmMessagesForSession, loadTranscriptHistoryRowsForSession, loadTranscriptRows, loadTranscriptRowsForSession, markMemoryRecordsConflicted, mergeUserPeople, metadataToSessionInsert, mutateQueuedSessionInput, openXopcDatabase, paginateTranscriptMessages, patchSessionMetadata, pruneBoundedKnowledgeSourceItems, readSchemaVersion, readSchemaVersionForTest, reconcileConnectorAccount, recordActivityEvent, recordContextConsolidationDecision, recordContextFeedback, recordContextRun, recoverSessionInputState, recoverStaleConnectorLearningJobs, refreshConnectorAccountCurrent, rejectUnderstanding, releaseConnectorWebhookDelivery, replaceConnectorCatalogEntries, replaceLatestSessionTurnAndQueueInput, replaceTranscriptRows, replaceUserPeopleIndex, requireXopcDatabase, resetSessionRecord, resetXopcDatabaseSingletonForTest, resolveMigrationsDir, resolveSessionAgentId, resolveXopcDatabasePath, restoreBeforeCompactionBoundary, reviseCollaborationRule, reviseUnderstanding, revokeDevice, revokeEndpointPrincipal, rotateDeviceRefreshToken, runSqliteWriteTransaction, searchActiveUnderstandings, searchMemoryRecords, searchSessionTranscript, sessionConfigRowToConfig, sessionRowToMetadata, setCollaborationRuleStatus, setConnectorLearningPaused, setEndpointSessionBinding, setInteractionState, setKnowledgeConsumerWatermark, setKnowledgeSourceCursor, setKnowledgeSourceItemSynthesisStatus, setMemoryProviderState, setMemoryRecordStatus, setMemoryTurnFeedback, setSessionConfig, setSessionInputStatus, setSessionTaskPlan, setUnderstandingStatus, setUserTrustPolicy, signGatewayPayload, startContextConsolidationRun, startEndpointToolInvocationAudit, startKnowledgeSyncRun, summarizeMemoryRecallFeedback, summarizeUnderstandingFeedback, summarizeUserPeople, summarizeUserUnderstandingQuality, touchEndpointPrincipal, transcriptEntryRowToStoredRow, updateConnectorLearningJob, updateInteractionStateFromMessage, updateRelationshipSettings, updateSessionConfig, updateSessionStats, updateUserPerson, updateUserProfile, upsertConnectorActionMetadata, upsertConnectorCatalogEntry, upsertConnectorConnection, upsertConnectorInstallation, upsertConnectorSyncPolicy, upsertKnowledgeSourceItems, upsertMemoryRecord, upsertNoteAgentContextRecord, upsertNoteRecord, validateLatestSessionTurnTarget };