@kraki/head 0.20.1 → 0.20.3

package/dist/server/voice-lease.js

@@ -0,0 +1,111 @@
+/** Voice leases: short-lived credentials for the voice service, within the daily quota. */
+import { getLogger } from '../logger.js';
+import { DEFAULT_VOICE_LEASE_TTL_SEC, DEFAULT_VOICE_DAILY_QUOTA_SEC, MIN_VOICE_LEASE_GRANT_SEC, VALID_VOICE_RESOURCES } from './shared.js';
+export function handleRequestVoiceLease(server, ws, state, msg) {
+    const logger = getLogger();
+    const userId = state.userId;
+    const deviceId = state.deviceId;
+    if (!userId || !deviceId) {
+        ws.send(JSON.stringify({
+            type: 'voice_lease_denied',
+            reason: 'invalid_request',
+            detail: 'Not authenticated',
+        }));
+        return;
+    }
+    const issuer = server.options.leaseIssuer;
+    if (!issuer) {
+        server.sendControlToDevice(deviceId, {
+            type: 'voice_lease_denied',
+            reason: 'not_entitled',
+            detail: 'Voice lease issuance is not enabled on this head',
+        });
+        return;
+    }
+    // Validate request shape.
+    const requestedDeviceId = typeof msg.deviceId === 'string' ? msg.deviceId : undefined;
+    const requestedResource = typeof msg.resource === 'string' ? msg.resource : undefined;
+    if (!requestedDeviceId || !requestedResource) {
+        server.sendControlToDevice(deviceId, {
+            type: 'voice_lease_denied',
+            reason: 'invalid_request',
+            detail: 'Missing deviceId or resource',
+        });
+        return;
+    }
+    // Lease may only be requested for the authenticated device — no proxying.
+    if (requestedDeviceId !== deviceId) {
+        server.sendControlToDevice(deviceId, {
+            type: 'voice_lease_denied',
+            reason: 'invalid_request',
+            detail: 'deviceId does not match authenticated device',
+        });
+        return;
+    }
+    if (!VALID_VOICE_RESOURCES.has(requestedResource)) {
+        server.sendControlToDevice(deviceId, {
+            type: 'voice_lease_denied',
+            reason: 'invalid_request',
+            detail: `Unknown resource: ${String(requestedResource)}`,
+        });
+        return;
+    }
+    // A lease is a long-lived credential for this device; the audio budget
+    // is granted incrementally by usage reports, charged to the UTC day the
+    // audio is used. So issuance only checks that anything is left today.
+    const nowSec = Math.floor(Date.now() / 1000);
+    const dailyCap = server.options.voiceDailyQuotaSec ?? DEFAULT_VOICE_DAILY_QUOTA_SEC;
+    server.storage.revokePendingVoiceLeases(userId, deviceId, requestedResource, nowSec);
+    const accountedToday = server.storage.voiceSecondsAccountedToday(userId, nowSec);
+    if (dailyCap - accountedToday < MIN_VOICE_LEASE_GRANT_SEC) {
+        logger.info('Voice lease denied: daily quota exhausted', {
+            userId, deviceId, accountedToday, dailyCap,
+        });
+        server.sendControlToDevice(deviceId, {
+            type: 'voice_lease_denied',
+            reason: 'quota_exhausted',
+            detail: `Daily quota reached (${accountedToday}/${dailyCap}s)`,
+        });
+        return;
+    }
+    const ttl = server.options.voiceLeaseTtlSec ?? DEFAULT_VOICE_LEASE_TTL_SEC;
+    // Signed ceiling for one lease: all the UTC days it can span. The real
+    // limit is the daily grant Head hands out on each usage report.
+    const grant = dailyCap * (Math.ceil(ttl / 86_400) + 1);
+    const lease = issuer.issue({
+        userId,
+        deviceId,
+        quotaSeconds: grant,
+        ttlSeconds: ttl,
+        resource: requestedResource,
+        nowUnixSec: nowSec,
+    });
+    try {
+        server.storage.recordVoiceLease({
+            jti: lease.payload.jti,
+            userId,
+            deviceId,
+            resource: requestedResource,
+            quotaSeconds: grant,
+            issuedAtUnixSec: lease.payload.iat,
+            expiresAtUnixSec: lease.payload.exp,
+        });
+    }
+    catch (err) {
+        logger.error('Voice lease persist failed', {
+            userId, deviceId, jti: lease.payload.jti, error: err.message,
+        });
+        server.sendControlToDevice(deviceId, {
+            type: 'voice_lease_denied',
+            reason: 'invalid_request',
+            detail: 'Lease persistence failed',
+        });
+        return;
+    }
+    logger.info('Voice lease issued', {
+        userId, deviceId, jti: lease.payload.jti,
+        quotaSeconds: grant, ttlSec: ttl, accountedToday, dailyCap,
+    });
+    server.sendControlToDevice(deviceId, { type: 'voice_lease_grant', lease });
+}
+//# sourceMappingURL=voice-lease.js.map

package/dist/server/voice-lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-lease.js","sourceRoot":"","sources":["../../src/server/voice-lease.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -1,64 +1,24 @@
 import { WebSocket } from 'ws';
 import type { Server } from 'http';
+import type { VoiceCapability } from '@kraki/protocol';
 import { Storage } from './storage.js';
-import { LeaseIssuer } from './lease-issuer.js';
-import type { AuthProvider } from './auth.js';
-import type { PushManager } from './push/index.js';
+import { PulseHub } from './pulse-hub.js';
 import type { AuthBackend } from './auth-backend.js';
-export interface HeadServerOptions {
-    authProviders?: Map<string, AuthProvider>;
-    authProvider?: AuthProvider;
-    maxPayload?: number;
-    pairingEnabled?: boolean;
-    pairingTtl?: number;
-    version?: string;
-    pushManager?: PushManager;
-    /** Optional auth backend. If provided, auth is delegated to it instead of using local providers. */
-    authBackend?: AuthBackend;
-    /** This head's region identifier (e.g., 'us', 'china'). Sent to auth backend for region checks. */
-    region?: string;
-    /** Voice-broker lease signer. If absent, request_voice_lease is rejected with 'not_entitled'. */
-    leaseIssuer?: LeaseIssuer;
-    /** Lease (device voice credential) lifetime in seconds. Default 86400 (24h). */
-    voiceLeaseTtlSec?: number;
-    /** The only voice limit: max seconds of audio per user per UTC day. Default 7200 (2h). */
-    voiceDailyQuotaSec?: number;
-    /**
-     * Public WSS URL of the voice broker for this region (e.g.
-     * `wss://cn.stt.kraki.chat/voice`). When set, head advertises a
-     * `VoiceCapability` inside `auth_ok.voice` so arm can render the mic UI.
-     * When unset, the field is omitted entirely — arm hides the mic UI.
-     *
-     * Must be set together with `leaseIssuer`: cli-side interlock refuses to
-     * start in either-without-the-other configurations because:
-     *   - Advertising a broker URL but having no issuer would mean clients
-     *     show the mic UI then get `not_entitled` on every press.
-     *   - Having an issuer but no advertised URL means clients have no way
-     *     to actually use the leases they're being issued.
-     */
-    voiceBrokerUrl?: string;
-    /**
-     * Close sockets that have not authenticated within this time (ms).
-     * Default 15s. A socket that asked for `auth_info` (an app on its login
-     * screen, waiting for the user to finish signing in) gets
-     * `loginScreenAuthTimeoutMs` instead (default 10 min).
-     */
-    authTimeoutMs?: number;
-    loginScreenAuthTimeoutMs?: number;
-}
+import { type ClientState, type HeadServerOptions } from './server/shared.js';
+export type { HeadServerOptions } from './server/shared.js';
 export declare class HeadServer {
     private wss;
-    private storage;
-    private options;
+    storage: Storage;
+    options: HeadServerOptions;
     private static readonly PING_INTERVAL;
-    private connections;
-    private authBackend;
-    private userByDevice;
-    private clients;
+    connections: Map<string, WebSocket>;
+    authBackend: AuthBackend;
+    userByDevice: Map<string, string>;
+    clients: Map<WebSocket, ClientState>;
     private pingTimer;
     private livenessTimer;
     /** Per-hop pulse hub — the reliable-delivery layer for every connection. */
-    private pulseHub;
+    pulseHub: PulseHub;
     private pulseTickTimer;
     constructor(storage: Storage, options: HeadServerOptions);
     private startPingInterval;
@@ -76,7 +36,7 @@ export declare class HeadServer {
     private linkProgressing;
     /** Test hook: force a liveness sweep without waiting for the timer. */
     forceLivenessSweep(): void;
-    private getVapidPublicKey;
+    getVapidPublicKey(): string | undefined;
     /**
      * Build the voice capability advertisement for `auth_ok` from this head's
      * config. Returns `undefined` (omit the field) when no broker URL is
@@ -87,14 +47,13 @@ export declare class HeadServer {
      * advertises Beijing's broker, and US main advertises nothing, all from a
      * single helper.
      */
-    private getVoiceCapability;
+    getVoiceCapability(): VoiceCapability | undefined;
     attach(server: Server): void;
     acceptConnection(ws: WebSocket): void;
     /** (Re)start the deadline for this socket to authenticate (G1). */
     private armAuthTimer;
     private onConnection;
     private onMessage;
-    private handleRequestVoiceLease;
     /** Send a pulse frame (control or forwarded data) to a device's socket, as a
      *  minimal unicast envelope carrying only the `pulse` field. Returns true if
      *  the device is online. Used by the PulseHub to reach endpoints. */
@@ -105,27 +64,17 @@ export declare class HeadServer {
      *  wrapped as `{from:'@head', msg}` — the receiver's pulse layer recognizes the
      *  `@head` marker and dispatches `msg` WITHOUT decrypting. Non-durable:
      *  presence/prefs are ephemeral. */
-    private sendControlToDevice;
+    sendControlToDevice(deviceId: string, msg: Record<string, unknown>): void;
     /** Presence (device_joined/left/removed/pending): the destination's next
      *  `auth_ok` device list supersedes it, so it is never replayed across a
      *  reconnect (a stale device_left would hide an online peer). */
-    private sendPresenceToDevice;
+    sendPresenceToDevice(deviceId: string, msg: Record<string, unknown>): void;
     /** A pulse frame addressed to HEAD_PULSE_TARGET was delivered in-order by the
      *  source device's endpoint. The payload is PLAINTEXT control JSON. Resolve the
      *  originating authenticated connection and route it through the SAME control
      *  handlers the raw-WS path uses, so auth context (state.userId/deviceId) and
      *  responses (over ws) are identical. */
     private deliverPulseToSelf;
-    /** The relay-terminated control ops, callable from BOTH the raw-WS dispatch
-     *  (onMessage) and the pulse deliver-to-self path. Returns true if handled. */
-    private handleControlMessage;
-    /** Persist a preferences update and echo the merged result to the sender + the
-     *  user's other online devices. */
-    private handleUpdatePreferences;
-    /** Account data, not session data: no tentacle is involved. The sender
-     *  always gets the resulting list back (its acknowledgement); other online
-     *  apps of the account get it only when something was applied. */
-    private handleUpdateVoiceVocabulary;
     /** Fan-out targets for a pulse broadcast from `fromDevice`: all OTHER
      *  ONLINE devices of the same user. Offline devices are excluded because
      *  broadcasts (user_message / agent_message / delta / active / idle /
@@ -140,77 +89,16 @@ export declare class HeadServer {
      *  streaming delta arrives 16s later than the previous" bug). Reconnecting
      *  devices resync via session_messages_range instead. */
     private pulseBroadcastTargets;
-    /** Notify offline devices from a pushPreview side-channel. The preview rides the
-     *  same pulse broadcast envelope as the reliable message. */
-    private firePushPreview;
     private removeConnection;
-    private sendAuthError;
-    private handleAuth;
-    /** After an awaited auth step: is this socket still open, still ours and
-     *  still unauthenticated? The auth deadline may have closed it meanwhile;
-     *  registering a dead socket would evict the device's live connection. */
-    private socketStillAuthenticating;
-    private handleChallengeResponse;
-    /**
-     * Handle a result from AuthBackend — registers connection state and sends response.
-     * Used for both initial auth and challenge-response verification.
-     */
-    private handleBackendAuthResult;
-    /**
-     * Common post-auth completion logic, used by every auth path.
-     *
-     * Responsibilities:
-     *  - Read user preferences from local storage and merge into the user object.
-     *  - Flush any locally-queued pending messages for this device (offline-queue).
-     *  - Build and send the `auth_ok` response.
-     *  - Broadcast `device_joined` to the user's other connected devices.
-     *
-     * Each caller is responsible for path-specific work BEFORE calling this:
-     * validating credentials, persisting user/device records, setting up
-     * ClientState, populating `connections` / `userByDevice` maps, and logging
-     * the path-specific "authenticated via X" line.
-     *
-     * Centralising the tail eliminates a class of bugs where new auth paths
-     * (notably the multi-region delegated-backend path) silently diverge from
-     * the established post-auth flow.
-     */
-    private completeAuthHandshake;
-    /**
-     * A device is about to register `ws` as its connection. If the SAME device id
-     * already had a socket, that older socket is now orphaned: once we overwrite
-     * the map entry its close handler hits the reconnect-guard and skips cleanup,
-     * and the ping timer (which only walks `connections`) never visits it again.
-     * It would sit in `clients` holding its ClientState until TCP finally gives
-     * up. Retire both the WebSocket and its Pulse link explicitly before the new
-     * connection is installed.
-     *
-     * Must be called BEFORE `connections.set(deviceId, ws)`.
-     */
-    private evictPreviousConnection;
-    private handleCreatePairingToken;
-    private handleRequestPairingToken;
-    private handleRemoveDevice;
     /** Users whose deletion is in flight (a double tap must not run it twice). */
-    private deletingAccounts;
-    /**
-     * Delete the requesting user's account: at the account store (the account
-     * service in edge mode) and in this relay's own storage and pulse state.
-     * Then tell every connected device and close it. Devices that were offline
-     * get `auth_error` code `account_deleted` when they next connect.
-     */
-    private handleDeleteAccount;
-    private handleRegisterPushToken;
-    private handleUnregisterPushToken;
-    private broadcastDeviceRemoved;
-    private broadcastDeviceJoined;
-    private broadcastDeviceLeft;
-    private broadcastDevicePending;
+    deletingAccounts: Set<string>;
     /** Handle pong from either protocol-level or JSON pong.
      *  Re-promotes to device_joined if we already broadcast device_pending.
      *  Guards against stale pongs from replaced connections (reconnect race). */
     private onPongReceived;
-    private getDeviceSummaries;
-    private sendError;
+    sendError(ws: WebSocket, message: string): void;
+    /** Live gauges for `/internal/metrics` (counts only). */
+    getGauges(): Record<string, number>;
     getStats(): {
         users: {
             total: number;