@qilin-agent/cli 3.1.3 → 3.1.4

package/lib/tenants-roster-Bhr9x2Jw.js

@@ -0,0 +1,252 @@
+import { a as isTenantIdentity } from "./tenant-runtime-ChD53FKq.js";
+import { resolveQilinHome } from "@qilin-agent/home-paths";
+import { mkdir, rm, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+import { AccountStore, MIN_PASSWORD_LENGTH, accountsFilePath, isValidEmail, isValidUsername, normalizeEmail, normalizeUsername } from "@qilin-agent/accounts-local";
+//#region lib/types/tenants-roster.js
+/**
+* `qilin tenants` roster operations: the account file every tenant runtime on
+* this Harness home shares, and the tenant directory each account owns.
+*
+* A tenant runtime admits exactly the account it serves, so a new account
+* cannot be created through a tenant's own Web surface (its registration is
+* closed). These commands are how a deployment adds, re-keys, and retires the
+* accounts its tenant runtimes serve.
+* @module @qilin-agent/cli/tenants-roster
+*/
+/** Absolute tenant directory one account owns. */
+function tenantDirectory(home, accountId) {
+	return join(home, "tenants", accountId);
+}
+/** Whether a path exists. */
+async function exists(path) {
+	return await stat(path).then(() => true, () => false);
+}
+/** Open the shared home's roster. */
+async function roster(home) {
+	return await AccountStore.open(accountsFilePath(home));
+}
+/**
+* Every account of one shared home with the tenant directory it owns.
+* @param home - absolute shared Harness home.
+* @returns one entry per account, oldest first.
+*/
+async function rosterEntries(home) {
+	const store = await roster(home);
+	return await Promise.all(store.all().map(async (account) => ({
+		id: account.id,
+		username: account.username,
+		email: account.email,
+		createdAt: account.createdAt,
+		tenantDirectory: tenantDirectory(home, account.id),
+		tenantDataPresent: await exists(tenantDirectory(home, account.id))
+	})));
+}
+/**
+* Create one account in the shared roster.
+* @param home - absolute shared Harness home.
+* @param request - the login name, address, password, and administrator seat.
+* @returns the created account.
+* @throws Error when the name or address is refused or already taken, or when
+* the deployment already has an administrator.
+*/
+async function addAccount(home, request) {
+	const username = normalizeUsername(request.username);
+	if (!isValidUsername(username)) throw new Error(`qilin tenants: '${request.username}' is not an acceptable username: 3-32 characters of a-z, 0-9, '_', '.', or '-', starting with a letter or digit`);
+	if (request.password.length < MIN_PASSWORD_LENGTH) throw new Error(`qilin tenants: a password needs at least ${String(MIN_PASSWORD_LENGTH)} characters`);
+	const store = await roster(home);
+	if (store.byUsername(username) !== void 0) throw new Error(`qilin tenants: the account ${username} already exists`);
+	let email = null;
+	if (request.email !== void 0 && request.email.trim() !== "") {
+		email = normalizeEmail(request.email);
+		if (!isValidEmail(email)) throw new Error(`qilin tenants: '${request.email}' is not an acceptable email address`);
+		if (store.byEmail(email) !== void 0) throw new Error(`qilin tenants: the address ${email} already belongs to an account`);
+	}
+	return await store.add({
+		username,
+		email
+	}, request.password, { admin: request.admin === true });
+}
+/**
+* Replace one account's password, retiring the sessions the previous one issued.
+* @param home - absolute shared Harness home.
+* @param username - the account's login name, normalized before lookup.
+* @param password - the replacement password.
+* @returns the stored successor.
+* @throws Error when no account has that name or the password is too short.
+*/
+async function setAccountPassword(home, username, password) {
+	if (password.length < MIN_PASSWORD_LENGTH) throw new Error(`qilin tenants: a password needs at least ${String(MIN_PASSWORD_LENGTH)} characters`);
+	const store = await roster(home);
+	const account = store.byUsername(normalizeUsername(username));
+	if (account === void 0) throw new Error(`qilin tenants: no account is named ${normalizeUsername(username)}`);
+	return await store.setPassword(account.id, password);
+}
+/**
+* Remove one account from the shared roster.
+*
+* A running tenant runtime keeps serving the account until it is reclaimed or
+* restarted; a runtime started afterwards fails loud, because the overlay
+* admits an account the roster no longer holds.
+* @param home - absolute shared Harness home.
+* @param username - the account's login name, normalized before lookup.
+* @param purgeData - also remove that account's tenant directory.
+* @returns the removed account and, when asked, the removed directory.
+* @throws Error when no account has that name, or when the tenant directory is not where it belongs.
+*/
+async function removeAccount(home, username, purgeData) {
+	const store = await roster(home);
+	const account = store.byUsername(normalizeUsername(username));
+	if (account === void 0) throw new Error(`qilin tenants: no account is named ${normalizeUsername(username)}`);
+	const directory = tenantDirectory(home, account.id);
+	const resolved = resolve(directory);
+	if (purgeData && (!isTenantIdentity(account.id) || dirname(resolved) !== resolve(join(home, "tenants")))) throw new Error(`qilin tenants: refusing to remove ${resolved}, which is not this account's tenant directory`);
+	const removed = await store.remove(account.id);
+	if (!purgeData || !await exists(directory)) return {
+		account: removed,
+		purgedDirectory: void 0
+	};
+	await rm(directory, {
+		recursive: true,
+		force: true
+	});
+	return {
+		account: removed,
+		purgedDirectory: directory
+	};
+}
+/**
+* Read one password from standard input without echoing it.
+* @param prompt - the text shown on standard error before reading.
+* @returns the entered line, without its terminator.
+* @throws Error when standard input is not a terminal, so an unattended run cannot wait for input.
+*/
+async function promptPassword(prompt) {
+	if (!process.stdin.isTTY) throw new Error("qilin tenants: standard input is not a terminal; pipe the password in and pass --password-stdin");
+	const silent = new Writable({ write(_chunk, _encoding, done) {
+		done();
+	} });
+	const prompt_ = createInterface({
+		input: process.stdin,
+		output: silent,
+		terminal: true
+	});
+	try {
+		process.stderr.write(prompt);
+		const entered = await prompt_.question("");
+		process.stderr.write("\n");
+		return entered;
+	} finally {
+		prompt_.close();
+	}
+}
+/**
+* Read the first line of standard input.
+* @returns the line, without its terminator.
+*/
+async function readStandardInput() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+	return (Buffer.concat(chunks).toString("utf8").split("\n")[0] ?? "").replace(/\r$/u, "");
+}
+/**
+* Read the password one mutation applies.
+* @param source - whether to prompt or read standard input.
+* @param label - the account being changed, named in the confirmation prompt.
+* @returns the password.
+* @throws Error when an interactive entry is not confirmed, or when standard input is a terminal without a prompt.
+*/
+async function readPassword(source, label) {
+	if (source.kind === "stdin") return await readStandardInput();
+	const entered = await promptPassword(`Password for ${label}: `);
+	if (entered !== await promptPassword("Repeat password: ")) throw new Error("qilin tenants: the two passwords differ");
+	return entered;
+}
+/** One roster row as the table prints it. */
+function formatRow(entry) {
+	const created = new Date(entry.createdAt).toISOString().slice(0, 10);
+	const data = entry.tenantDataPresent ? "yes" : "no";
+	return `${entry.username.padEnd(20)} ${entry.id} ${created} ${data.padEnd(3)} ${entry.email ?? "-"}`;
+}
+/**
+* Print the roster of one shared home.
+* @param home - absolute shared Harness home.
+* @param write - where each line goes.
+* @returns the printed entries.
+*/
+async function printRoster(home, write) {
+	const entries = await rosterEntries(home);
+	if (entries.length === 0) {
+		write(`qilin tenants: ${home} has no accounts yet; create one with: qilin tenants add <username>`);
+		return entries;
+	}
+	write("USERNAME             ID                                   CREATED    DATA EMAIL");
+	for (const entry of entries) write(formatRow(entry));
+	write(`qilin tenants: ${String(entries.length)} account(s) in ${accountsFilePath(home)}`);
+	return entries;
+}
+/**
+* Create the tenant directory one account owns, so its first runtime starts in
+* a directory that exists even before a browser visits it.
+* @param home - absolute shared Harness home.
+* @param accountId - the account whose directory to create.
+* @returns the absolute directory.
+*/
+async function ensureTenantDirectory(home, accountId) {
+	const directory = tenantDirectory(home, accountId);
+	await mkdir(directory, { recursive: true });
+	return directory;
+}
+/**
+* Run one roster subcommand over this Harness home and print what it did.
+*
+* Failures are reported as a message and a non-zero exit code rather than a
+* stack trace: every refusal here is something the operator can correct.
+* @param request - the roster subcommand and its arguments.
+* @returns the process exit code: 0 when the request was carried out, 1 when it was refused.
+*/
+async function runTenantsRoster(request) {
+	const home = resolveQilinHome();
+	try {
+		switch (request.command) {
+			case "accounts":
+				await printRoster(home, (line) => {
+					process.stdout.write(`${line}\n`);
+				});
+				return 0;
+			case "add": {
+				const password = await readPassword(request.password, request.username);
+				const account = await addAccount(home, {
+					username: request.username,
+					email: request.email,
+					password,
+					admin: request.admin
+				});
+				const directory = await ensureTenantDirectory(home, account.id);
+				process.stdout.write(`qilin tenants: created ${account.username} (${account.id}); its tenant directory is ${directory}\n`);
+				if (account.admin === true) process.stdout.write(`qilin tenants: ${account.username} is this deployment's administrator and reads every account's usage ledger\n`);
+				return 0;
+			}
+			case "passwd": {
+				const password = await readPassword(request.password, request.username);
+				const account = await setAccountPassword(home, request.username, password);
+				process.stdout.write(`qilin tenants: replaced the password of ${account.username}; sessions it issued no longer verify\n`);
+				return 0;
+			}
+			case "remove": {
+				const removed = await removeAccount(home, request.username, request.purgeData);
+				const kept = removed.purgedDirectory === void 0 ? `its Sessions stay in ${tenantDirectory(home, removed.account.id)}` : `its tenant directory ${removed.purgedDirectory} is gone`;
+				process.stdout.write(`qilin tenants: retired ${removed.account.username} (${removed.account.id}); ${kept}\n`);
+				return 0;
+			}
+			default: throw new Error(`qilin tenants: unhandled roster subcommand ${JSON.stringify(request)}`);
+		}
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+}
+//#endregion
+export { runTenantsRoster };

package/lib/types/args.d.ts

@@ -14,6 +14,7 @@
  * plugin dependencies by forwarding to pnpm.
  * @module @qilin-agent/cli/args
  */
+import type { RosterRequest } from './tenants-roster.ts';
 /** Boot a named profile and hand it the invocation's inner arguments. */
 interface ProfileInvocation {
     mode: 'profile';
@@ -42,8 +43,16 @@ interface PluginInvocation {
     /** Raw pnpm arguments, verbatim. */
     args: string[];
 }
+/** What one `qilin tenants` invocation asks for. */
+type TenantsRequest = RosterRequest;
+/** Serve one isolated Web runtime per account, or manage this home's roster. */
+interface TenantsInvocation {
+    mode: 'tenants';
+    /** The validated subcommand and the options it takes. */
+    request: TenantsRequest;
+}
 /** The resolved `qilin` invocation. Help, version, and errors exit inside {@link parseQilinArgs}. */
-export type QilinInvocation = ProfileInvocation | DumpConfigInvocation | PluginInvocation;
+export type QilinInvocation = ProfileInvocation | DumpConfigInvocation | PluginInvocation | TenantsInvocation;
 /**
  * Resolve argv into one invocation, or print and exit for help, version, or an
  * error.

package/lib/types/scheduler-yield.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Host fallback for the Web Scheduler API global.
+ * @module @qilin-agent/cli/scheduler-yield
+ */
+/**
+ * Install `globalThis.scheduler.yield` unless the host already defines a
+ * `scheduler`.
+ *
+ * The fallback resolves on the next `setImmediate` — the API's "yield to the
+ * event loop once, then continue" semantic — and a host-provided `scheduler`
+ * is left untouched. Call it before importing anything that may read the
+ * global; `bin.ts` calls it at the top of the entry, ahead of every mode
+ * module. Rationale: [the host-shim Agent
+ * Note](../../../.agents/notes/implemented/architecture/2026-10-07-web-scheduler-yield-host-shim.md).
+ *
+ * @returns whether this call installed the fallback.
+ */
+export declare function installSchedulerYield(): boolean;
+//# sourceMappingURL=scheduler-yield.d.ts.map

package/lib/types/tenant-proxy.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The hub's transport hop into one tenant runtime: an HTTP request forwarded
+ * with that runtime's own authority, and an upgraded socket piped the same way.
+ *
+ * The hop changes transport facts only. It rewrites `Host` to the tenant's
+ * authority — the tenant's session cookie is named after the authority it was
+ * issued for, so one browser can hold one cookie per tenant on one origin —
+ * and rewrites `Origin` to that same authority after checking the browser's
+ * own Origin names the hub, which keeps the tenant's same-origin fence as
+ * strong as it is without a proxy. Everything else, including `Range`,
+ * `Set-Cookie`, `Location`, and partial-content answers, crosses unchanged.
+ *
+ * The hop decides no access: the tenant runtime's own account gate answers
+ * every request, so a forged routing cookie reaches a runtime that does not
+ * recognize the caller.
+ * @module @qilin-agent/cli/tenant-proxy
+ */
+import { type IncomingHttpHeaders, type IncomingMessage, type ServerResponse } from 'node:http';
+import { Readable, type Duplex } from 'node:stream';
+/** One request the hub forwards. */
+export interface ProxyRequestOptions {
+    /** Origin the runtime serves, such as `http://127.0.0.1:41234`. */
+    readonly origin: string;
+    /** Request method, verbatim. */
+    readonly method: string;
+    /** Path and query to request upstream, exactly the path the browser asked for. */
+    readonly path: string;
+    /** Browser headers, verbatim. */
+    readonly headers: IncomingHttpHeaders;
+    /** Browser authority that reached the hub, checked against the Origin fence. */
+    readonly hubAuthority: string;
+    /** Incoming body, when the request carries one. */
+    readonly body?: Readable | undefined;
+}
+/** One upstream answer, still streaming. */
+export interface ProxyAnswer {
+    /** Status code the runtime answered. */
+    readonly status: number;
+    /** Answer headers, hop-by-hop entries removed. */
+    readonly headers: IncomingHttpHeaders;
+    /** Answer body. */
+    readonly stream: Readable;
+}
+/**
+ * Whether a browser-labeled request may be forwarded at all.
+ *
+ * Over plain HTTP a read carries neither Origin nor Fetch-Metadata, so an
+ * absent Origin is accepted and the tenant's own Host fence still binds the
+ * request. A present Origin must name the hub exactly, and an explicit
+ * cross-site marker is refused: the hub is the outermost hop, so this is the
+ * only place those markers can be read before the tenant's authority replaces
+ * them.
+ * @param headers - browser headers, verbatim.
+ * @param hubAuthority - authority the browser used to reach the hub.
+ * @returns true when the request may be forwarded.
+ */
+export declare function hubAcceptsOrigin(headers: IncomingHttpHeaders, hubAuthority: string): boolean;
+/**
+ * Headers to forward upstream: the browser's own, minus connection-scoped
+ * entries, with the authority-bearing ones rewritten to the tenant.
+ * @param headers - browser headers, verbatim.
+ * @param tenantAuthority - the runtime's own `host:port`.
+ * @param deploymentAuthority - authority the browser used to reach the hub, and
+ * therefore the one the runtime names its sessions for; empty when the request
+ * reached a runtime directly, which then keeps its own authority as the name.
+ * Required rather than optional because every hop of this deployment knows it,
+ * and an upgrade that forgot it authenticates against a cookie no browser holds.
+ * @returns the forwarded header set.
+ */
+export declare function forwardedHeaders(headers: IncomingHttpHeaders, tenantAuthority: string, deploymentAuthority: string): IncomingHttpHeaders;
+/**
+ * Send one request to a tenant runtime and hand back its streaming answer.
+ *
+ * The hub's own origin fence runs here, in the operation that would forward the
+ * request, so no caller can forward a browser request whose Origin names
+ * another site.
+ * @param options - the runtime, the path, headers, and body to forward.
+ * @returns the runtime's status, headers, and body, or the refusal.
+ * @throws Error when the runtime is unreachable or refuses the connection.
+ */
+export declare function proxyRequest(options: ProxyRequestOptions): Promise<ProxyAnswer>;
+/**
+ * Write one upstream answer to the browser, streaming the body.
+ * @param answer - the runtime's status, headers, and body.
+ * @param response - the browser's response.
+ */
+export declare function relayAnswer(answer: ProxyAnswer, response: ServerResponse): void;
+/**
+ * Pipe one upgraded browser socket to the same path on a tenant runtime, with
+ * the tenant's authority in place of the hub's.
+ *
+ * The upgrade is piped, never terminated: the hub holds no copy of the frames,
+ * so the tenant's own mux and its trust fence stay in charge of the stream.
+ * @param request - the browser's upgrade request.
+ * @param socket - the browser's socket.
+ * @param head - bytes already read from the browser.
+ * @param target - origin of the runtime the socket belongs to.
+ * @param headers - already-forwarded headers, with the tenant's authority set.
+ */
+export declare function relayUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, target: string, headers: IncomingHttpHeaders): void;
+//# sourceMappingURL=tenant-proxy.d.ts.map