dsh-mobile 0.1.0-alpha.1

package/lib/index.d.mts

@@ -0,0 +1,409 @@
+import z from "@deepseek-ai/schemastery";
+import { WebRoute } from "@deepseek-ai/dsh-host-webserver";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/storage.d.ts
+/** Persistent record containing only a digest of the long-lived device credential. */
+interface StoredDevice {
+  readonly id: string;
+  readonly label: string;
+  readonly tokenDigest: string;
+  readonly createdAt: number;
+  readonly expiresAt: number;
+  readonly lastSeenAt: number;
+  readonly revokedAt?: number;
+}
+/** Versioned device state. Raw device and Session credentials are never members. */
+interface DeviceSnapshot {
+  readonly version: 1;
+  readonly devices: readonly StoredDevice[];
+}
+/** Persistence seam for device-token digests and revocation metadata. */
+interface DeviceStore {
+  load(): Promise<DeviceSnapshot>;
+  save(snapshot: DeviceSnapshot): Promise<void>;
+}
+/** Validate durable data before it can authorize a device. */
+declare function parseDeviceSnapshot(value: unknown, maximumDevices?: number): DeviceSnapshot;
+/** Atomic JSON implementation with symlink refusal and owner-only file creation. */
+declare class JsonDeviceStore implements DeviceStore {
+  private readonly file;
+  private readonly maximumDevices;
+  constructor(file: string, maximumDevices?: number);
+  load(): Promise<DeviceSnapshot>;
+  save(snapshot: DeviceSnapshot): Promise<void>;
+}
+/** In-memory store useful for embedding and deterministic tests. */
+declare class MemoryDeviceStore implements DeviceStore {
+  private snapshot;
+  constructor(initial?: DeviceSnapshot);
+  load(): Promise<DeviceSnapshot>;
+  save(snapshot: DeviceSnapshot): Promise<void>;
+  /** Return a defensive copy for assertions or administrative export. */
+  inspect(): DeviceSnapshot;
+}
+//#endregion
+//#region src/access.d.ts
+/** Stable error categories converted to deliberately terse HTTP responses. */
+declare class AccessError extends Error {
+  readonly status: number;
+  readonly code: string;
+  constructor(status: number, code: string);
+}
+/** Resource and lifetime controls for device authentication. */
+interface AccessControllerOptions {
+  readonly pairingTtlMs: number;
+  readonly deviceTtlMs: number;
+  readonly sessionTtlMs: number;
+  readonly maxDevices: number;
+  readonly maxSessions: number;
+  readonly rateLimitWindowMs: number;
+  readonly maxPairingAttempts: number;
+  readonly maxRateLimitKeys: number;
+  readonly now?: () => number;
+}
+/** Values issued once after pairing; only digests survive the response. */
+interface PairingResult {
+  readonly deviceId: string;
+  readonly deviceToken: string;
+  readonly deviceExpiresAt: number;
+  readonly sessionToken: string;
+  readonly csrfToken: string;
+  readonly sessionExpiresAt: number;
+}
+/** Values issued after renewal with the persistent HttpOnly device Cookie. */
+interface RenewalResult {
+  readonly deviceId: string;
+  readonly sessionToken: string;
+  readonly csrfToken: string;
+  readonly sessionExpiresAt: number;
+}
+/** Authenticated Session identity retained only inside the gateway. */
+interface SessionAuthorization {
+  readonly sessionKey: string;
+  readonly deviceId: string;
+  readonly expiresAt: number;
+}
+/** Safe device metadata returned by the loopback administration API. */
+interface DeviceSummary {
+  readonly id: string;
+  readonly label: string;
+  readonly createdAt: number;
+  readonly expiresAt: number;
+  readonly lastSeenAt: number;
+  readonly revokedAt?: number;
+}
+/** Fixed-window limiter whose attacker-controlled key table is itself bounded. */
+declare class BoundedRateLimiter {
+  private readonly limit;
+  private readonly windowMs;
+  private readonly maximumKeys;
+  private readonly buckets;
+  constructor(limit: number, windowMs: number, maximumKeys: number);
+  /** Consume one attempt; unknown keys fail closed when the bounded table is full. */
+  take(key: string, now: number): boolean;
+  /** Current table size, exposed for bounded-state assertions. */
+  get size(): number;
+}
+/** Pairing, persistent-device, short-Session, revocation, and CSRF state machine. */
+declare class AccessController {
+  private readonly store;
+  private readonly options;
+  private readonly now;
+  private readonly pairLimiter;
+  private devices;
+  private pairingWindow;
+  private readonly sessions;
+  private readonly sessionEndedListeners;
+  private mutation;
+  private initialized;
+  private closing;
+  private closeTask;
+  constructor(store: DeviceStore, options: AccessControllerOptions);
+  /** Load and validate digest-only durable state before accepting traffic. */
+  initialize(): Promise<void>;
+  private requireInitialized;
+  private exclusive;
+  private snapshot;
+  private emitSessionEnded;
+  private removeSession;
+  private pruneSessions;
+  private createSession;
+  /** Open one short pairing window and return its one-time secret to a loopback caller only. */
+  openPairing(requestedTtlMs?: number): Promise<{
+    token: string;
+    expiresAt: number;
+  }>;
+  /** Consume the pairing window exactly once and persist only the device-token digest. */
+  pair(sourceKey: string, token: string, label?: string): Promise<PairingResult>;
+  /** Exchange a valid persistent device credential for a new short Session. */
+  renew(deviceToken: string): Promise<RenewalResult>;
+  /** Resolve a short Session Cookie without revealing whether device or Session failed. */
+  authorizeSession(sessionToken: string): SessionAuthorization;
+  /** Require the Session-bound anti-CSRF value for an authenticated mutation. */
+  assertCsrf(authorization: SessionAuthorization, csrfToken: string | undefined): void;
+  /** End one short Session and notify the gateway to abort its attached work. */
+  logout(authorization: SessionAuthorization): void;
+  /** Persist revocation, then end every Session owned by that device. */
+  revokeDevice(deviceId: string): Promise<boolean>;
+  /** Remove every persistent credential and terminate every active Session. */
+  resetDevices(): Promise<void>;
+  /** Safe metadata for the loopback administration surface. */
+  listDevices(): readonly DeviceSummary[];
+  /** Pairing status without exposing the one-time secret. */
+  pairingStatus(): {
+    open: boolean;
+    expiresAt?: number;
+  };
+  /** Subscribe gateway resources to Session logout, expiry, eviction, and device revocation. */
+  onSessionEnded(listener: (authorization: SessionAuthorization) => void): () => void;
+  /** Stop new operations, drain durable mutations, then clear volatile credentials. */
+  close(): Promise<void>;
+  private finishClose;
+  /** Bounded volatile-state metrics for tests and local status. */
+  metrics(): {
+    sessions: number;
+    rateLimitKeys: number;
+  };
+}
+//#endregion
+//#region src/network.d.ts
+/** A parsed IP network used to authorize directly connected clients. */
+interface ParsedCidr {
+  readonly bits: 32 | 128;
+  readonly network: bigint;
+  readonly prefix: number;
+  readonly source: string;
+}
+/** A normalized public authority. A missing port is filled from the bound listener. */
+interface AuthoritySpec {
+  readonly hostname: string;
+  readonly port?: number;
+}
+/** Parse and canonicalize one IPv4 or IPv6 CIDR. */
+declare function parseCidr(source: string): ParsedCidr;
+/** Whether a directly connected socket address belongs to at least one allowed CIDR. */
+declare function addressAllowed(address: string | undefined, cidrs: readonly ParsedCidr[]): boolean;
+/** Whether an IP literal is loopback and therefore eligible for HTTP-only development. */
+declare function isLoopbackAddress(address: string): boolean;
+/** Parse a bare host or host:port authority without accepting URL components. */
+declare function parseAuthority(source: string): AuthoritySpec;
+/** Resolve an authority against the actual listener port. */
+declare function resolveAuthority(spec: AuthoritySpec, listenerPort: number): string;
+/** Exact Host/Origin/CIDR policy for the directly exposed listener. */
+declare class RequestTrustPolicy {
+  readonly cidrs: readonly ParsedCidr[];
+  readonly authorities: ReadonlySet<string>;
+  readonly origins: ReadonlySet<string>;
+  private readonly scheme;
+  constructor(specs: readonly AuthoritySpec[], listenerPort: number, cidrs: readonly ParsedCidr[], tls: boolean);
+  /** Validate the exact Host header after WHATWG authority normalization. */
+  acceptsHost(header: string | undefined): boolean;
+  /** Return the canonical accepted Host authority, otherwise undefined. */
+  canonicalHost(header: string | undefined): string | undefined;
+  /** Validate an exact same-scheme browser Origin. */
+  acceptsOrigin(header: string | undefined): boolean;
+  /** Return the canonical accepted Origin, otherwise undefined. */
+  canonicalOrigin(header: string | undefined): string | undefined;
+}
+//#endregion
+//#region src/config.d.ts
+/** TLS source accepted by the LAN listener. */
+interface ProvidedTlsConfig {
+  readonly mode: 'provided';
+  /** PEM server leaf followed by any intermediate certificate chain. */
+  readonly certFile: string;
+  readonly keyFile: string;
+  /** Optional PEM intermediates appended after the chain in `certFile`; roots are rejected. */
+  readonly caFile?: string;
+}
+/** HTTP is available only for an explicitly loopback-bound listener. */
+interface DisabledTlsConfig {
+  readonly mode: 'disabled';
+}
+type TlsConfig = ProvidedTlsConfig | DisabledTlsConfig;
+/** Operator-facing plugin configuration. */
+interface PluginConfig {
+  /** Optional setup JSON written by the packaged CLI. */
+  setupFile?: string;
+  /** Preferred HTTPS origin used to derive the public authority and listener port. */
+  publicOrigin?: string;
+  listenHost?: string;
+  listenPort?: number;
+  upstreamOrigin?: string;
+  publicAuthorities?: string[];
+  allowedCidrs?: string[];
+  stateFile: string;
+  /** Internal persisted on/off preference managed by the DSH plugin card. */
+  controlFile: string;
+  /** Optional user stylesheet served to both the desktop and authenticated mobile UI. */
+  customCssFile?: string;
+  /** First-run state used only while the control file does not exist. */
+  initiallyEnabled: boolean;
+  tls?: {
+    mode?: 'provided' | 'disabled';
+    certFile?: string;
+    keyFile?: string;
+    caFile?: string;
+  };
+  pairingTtlMs?: number;
+  deviceTtlMs?: number;
+  sessionTtlMs?: number;
+  maxDevices?: number;
+  maxSessions?: number;
+  maxConnections?: number;
+  maxActiveRequests?: number;
+  maxWebSockets?: number;
+  maxBodyBytes?: number;
+  upstreamTimeoutMs?: number;
+  rateLimitWindowMs?: number;
+  maxPairingAttempts?: number;
+  maxRateLimitKeys?: number;
+}
+/** Resolved, validated security and resource limits. */
+interface ResolvedGatewayConfig {
+  readonly listenHost: string;
+  readonly listenPort: number;
+  readonly upstreamOrigin: URL;
+  readonly authorities: readonly AuthoritySpec[];
+  readonly allowedCidrs: readonly ParsedCidr[];
+  readonly stateFile: string;
+  readonly customCssFile: string;
+  readonly tls: TlsConfig;
+  readonly pairingTtlMs: number;
+  readonly deviceTtlMs: number;
+  readonly sessionTtlMs: number;
+  readonly maxDevices: number;
+  readonly maxSessions: number;
+  readonly maxConnections: number;
+  readonly maxActiveRequests: number;
+  readonly maxWebSockets: number;
+  readonly maxBodyBytes: number;
+  readonly upstreamTimeoutMs: number;
+  readonly rateLimitWindowMs: number;
+  readonly maxPairingAttempts: number;
+  readonly maxRateLimitKeys: number;
+}
+/** Loader-facing defaults; {@link parseGatewayConfig} enforces cross-field security rules. */
+declare const Config: z<PluginConfig>;
+/** Resolve the hidden runtime-control file independently from gateway configuration. */
+declare function parseControlFile(value: unknown): string;
+/** Parse configuration and reject unsafe topology, credential, and resource combinations. */
+declare function parseGatewayConfig(raw: unknown): ResolvedGatewayConfig;
+//#endregion
+//#region src/control.d.ts
+/** Versioned durable preference for the resident mobile-access runtime. */
+interface MobileAccessControlState {
+  readonly version: 1;
+  readonly enabled: boolean;
+}
+/** Persistence seam for the runtime preference. */
+interface MobileAccessControlStore {
+  load(): Promise<MobileAccessControlState>;
+  save(state: MobileAccessControlState): Promise<void>;
+}
+/** One started gateway runtime owned by the controller. */
+interface MobileAccessRuntime {
+  close(): Promise<void>;
+}
+/** Validate control state loaded across the filesystem boundary. */
+declare function parseMobileAccessControlState(value: unknown): MobileAccessControlState;
+/** Atomic JSON store whose absent-file state comes from the installation-time default. */
+declare class JsonMobileAccessControlStore implements MobileAccessControlStore {
+  private readonly file;
+  private readonly initiallyEnabled;
+  constructor(file: string, initiallyEnabled: boolean);
+  load(): Promise<MobileAccessControlState>;
+  save(state: MobileAccessControlState): Promise<void>;
+}
+/** Serialized persistent lifecycle for the gateway behind the always-loaded Cordis entry. */
+declare class MobileAccessGatewayController {
+  private readonly store;
+  private readonly startRuntime;
+  private runtime;
+  private initialized;
+  private closing;
+  private queue;
+  private closeTask;
+  constructor(store: MobileAccessControlStore, startRuntime: () => Promise<MobileAccessRuntime>);
+  /** Load the durable preference and start the first runtime when enabled. */
+  initialize(): Promise<void>;
+  /** Return the committed in-process runtime state. */
+  isRunning(): boolean;
+  /** Start or stop the runtime and persist only a successfully committed transition. */
+  setRunning(running: boolean): Promise<void>;
+  /** Stop the runtime after earlier transitions without changing the restart preference. */
+  close(): Promise<void>;
+  private enable;
+  private disable;
+  private enqueue;
+}
+//#endregion
+//#region src/gateway.d.ts
+/** Authenticated TLS edge in front of the ordinary loopback-only DSH Web server. */
+declare class MobileAccessGateway {
+  readonly config: ResolvedGatewayConfig;
+  readonly access: AccessController;
+  private readonly tlsEnabled;
+  private policy;
+  private server;
+  private listenerPort;
+  private readonly connectedSockets;
+  private readonly activeRequests;
+  private readonly activeWebSockets;
+  private nextOperationId;
+  private closing;
+  private started;
+  private closeTask;
+  private readonly removeSessionListener;
+  private readonly renewLimiter;
+  constructor(config: ResolvedGatewayConfig, store: DeviceStore);
+  /** Initialize durable state, validate TLS, and bind the externally reachable listener. */
+  start(): Promise<void>;
+  private closeFailedStart;
+  /** Actual bound address, available after start and safe for loopback status output. */
+  address(): {
+    host: string;
+    port: number;
+    origin: string;
+  };
+  private requirePolicy;
+  private authorize;
+  private requireCsrf;
+  private setSessionCookies;
+  private handlePair;
+  private handleRenew;
+  private handleLogout;
+  private handleExternalRequest;
+  private allocateRequest;
+  private proxyHttp;
+  private abortSessionResources;
+  private readUpgradeResponse;
+  private handleUpgrade;
+  /** Loopback-only DSH WebServer route for opening pairing and managing devices. */
+  localAdminRoute(): WebRoute;
+  /** Close listeners and abort all accepted work before resolving teardown. */
+  close(): Promise<void>;
+  private performClose;
+  /** Safe metadata helper for direct loopback integrations. */
+  devices(): readonly DeviceSummary[];
+}
+//#endregion
+//#region src/http-security.d.ts
+declare const DEVICE_COOKIE = "dsh_ma_device";
+declare const SESSION_COOKIE = "dsh_ma_session";
+declare const CSRF_COOKIE = "dsh_ma_csrf";
+declare const CSRF_HEADER = "x-dsh-mobile-csrf";
+declare const LOCAL_ADMIN_PREFIX = "/api/mobile-access";
+declare const AUTH_PREFIX = "/mobile-access";
+declare const WS_PATHS: Set<string>;
+//#endregion
+//#region src/plugin.d.ts
+/** Stable Cordis plugin name. */
+declare const name = "dsh-mobile";
+/** The stock WebServer is the only DSH Host service this plugin requires. */
+declare const inject: string[];
+/** Mount the resident control route and its optional authenticated LAN gateway. */
+declare function apply(ctx: Context, config: PluginConfig): Promise<void>;
+//#endregion
+export { AUTH_PREFIX, AccessController, type AccessControllerOptions, AccessError, type AuthoritySpec, BoundedRateLimiter, CSRF_COOKIE, CSRF_HEADER, Config, DEVICE_COOKIE, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, JsonDeviceStore, JsonMobileAccessControlStore, LOCAL_ADMIN_PREFIX, MemoryDeviceStore, type MobileAccessControlState, type MobileAccessControlStore, MobileAccessGateway, MobileAccessGatewayController, type MobileAccessRuntime, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, type RenewalResult, RequestTrustPolicy, type ResolvedGatewayConfig, SESSION_COOKIE, type SessionAuthorization, type StoredDevice, type TlsConfig, WS_PATHS, addressAllowed, apply, inject, isLoopbackAddress, name, parseAuthority, parseCidr, parseControlFile, parseDeviceSnapshot, parseGatewayConfig, parseMobileAccessControlState, resolveAuthority };
+//# sourceMappingURL=index.d.mts.map