@pikku/cli 0.12.39 → 0.12.41

package/dist/src/utils/cli-session.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A locally-persisted CLI session obtained via `pikku login` (the better-auth
+ * device-authorization flow). Stored at `~/.pikku/session.json`, keyed by the
+ * server's base URL so a single user can be logged into multiple pikku servers.
+ *
+ * `accessToken` is a better-auth session token — present it as
+ * `Authorization: Bearer <accessToken>` (requires the `bearer` plugin on the
+ * server). This is the HUMAN path; machine agents use scoped API keys
+ * (`x-api-key`) instead and never read this file.
+ */
+export interface PikkuCliSession {
+    baseURL: string;
+    accessToken: string;
+    tokenType: string;
+    /** ISO timestamp; absent when the server did not report an expiry. */
+    expiresAt?: string;
+    user?: {
+        id: string;
+        email?: string | null;
+        name?: string | null;
+    };
+    obtainedAt: string;
+}
+export declare const sessionFilePath: () => string;
+/** Drop a trailing slash so `https://x/` and `https://x` share one entry. */
+export declare const normalizeBaseURL: (url: string) => string;
+/** Persist a session and mark it the current default target. */
+export declare const saveSession: (session: PikkuCliSession) => Promise<string>;
+/**
+ * Load a stored session. With no `baseURL`, returns the current default. Returns
+ * `null` if none is stored.
+ */
+export declare const loadSession: (baseURL?: string) => Promise<PikkuCliSession | null>;
+/**
+ * Remove a stored session (the given one, or the current default). Returns the
+ * base URL that was removed, or `null` if nothing matched.
+ */
+export declare const clearSession: (baseURL?: string) => Promise<string | null>;
+/** True when the session has a known expiry that is in the past. */
+export declare const isSessionExpired: (session: PikkuCliSession, nowMs?: number) => boolean;

package/dist/src/utils/cli-session.js

@@ -0,0 +1,73 @@
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+const SESSION_DIR = join(homedir(), '.pikku');
+const SESSION_FILE = join(SESSION_DIR, 'session.json');
+export const sessionFilePath = () => SESSION_FILE;
+/** Drop a trailing slash so `https://x/` and `https://x` share one entry. */
+export const normalizeBaseURL = (url) => url.trim().replace(/\/+$/, '');
+const readSessionFile = async () => {
+    if (!existsSync(SESSION_FILE)) {
+        return { sessions: {} };
+    }
+    try {
+        const parsed = JSON.parse(await readFile(SESSION_FILE, 'utf-8'));
+        return { sessions: parsed.sessions ?? {}, current: parsed.current };
+    }
+    catch {
+        // Corrupt file — treat as empty rather than crashing every command.
+        return { sessions: {} };
+    }
+};
+const writeSessionFile = async (file) => {
+    await mkdir(dirname(SESSION_FILE), { recursive: true });
+    // 0600 — the file holds bearer tokens.
+    await writeFile(SESSION_FILE, JSON.stringify(file, null, 2), { mode: 0o600 });
+};
+/** Persist a session and mark it the current default target. */
+export const saveSession = async (session) => {
+    const file = await readSessionFile();
+    const key = normalizeBaseURL(session.baseURL);
+    file.sessions[key] = { ...session, baseURL: key };
+    file.current = key;
+    await writeSessionFile(file);
+    return SESSION_FILE;
+};
+/**
+ * Load a stored session. With no `baseURL`, returns the current default. Returns
+ * `null` if none is stored.
+ */
+export const loadSession = async (baseURL) => {
+    const file = await readSessionFile();
+    const key = baseURL ? normalizeBaseURL(baseURL) : file.current;
+    if (!key) {
+        return null;
+    }
+    return file.sessions[key] ?? null;
+};
+/**
+ * Remove a stored session (the given one, or the current default). Returns the
+ * base URL that was removed, or `null` if nothing matched.
+ */
+export const clearSession = async (baseURL) => {
+    const file = await readSessionFile();
+    const key = baseURL ? normalizeBaseURL(baseURL) : file.current;
+    if (!key || !file.sessions[key]) {
+        return null;
+    }
+    delete file.sessions[key];
+    if (file.current === key) {
+        file.current = Object.keys(file.sessions)[0];
+    }
+    if (Object.keys(file.sessions).length === 0) {
+        // Nothing left — remove the file entirely rather than leaving an empty husk.
+        await rm(SESSION_FILE, { force: true });
+    }
+    else {
+        await writeSessionFile(file);
+    }
+    return key;
+};
+/** True when the session has a known expiry that is in the past. */
+export const isSessionExpired = (session, nowMs = Date.now()) => session.expiresAt ? new Date(session.expiresAt).getTime() <= nowMs : false;

package/dist/src/utils/device-auth.d.ts

@@ -0,0 +1,28 @@
+import type { PikkuCliSession } from './cli-session.js';
+export interface DevicePrompt {
+    /** Where the user approves the request. */
+    verificationUri: string;
+    /** Same as above with the code pre-filled (open this if present). */
+    verificationUriComplete?: string;
+    userCode: string;
+    /** Absolute ms timestamp when the code expires. */
+    expiresAtMs: number;
+}
+export interface DeviceLoginOptions {
+    /** Server origin, e.g. `https://app.example.com`. */
+    baseURL: string;
+    /** better-auth basePath. Defaults to `/auth`. */
+    authBasePath?: string;
+    /** Logical client identifier (no OIDC registration required). */
+    clientId?: string;
+    /** Optional space-separated scopes to request. */
+    scope?: string;
+    /** Called once the device code is issued, so the caller can prompt the user. */
+    onPrompt: (prompt: DevicePrompt) => void | Promise<void>;
+}
+/**
+ * Run the better-auth device-authorization flow against `baseURL` and return a
+ * persisted-shaped session (token + best-effort expiry/user). The human
+ * approves in the browser; this only requests a code and polls for the token.
+ */
+export declare const deviceLogin: (opts: DeviceLoginOptions) => Promise<PikkuCliSession>;

package/dist/src/utils/device-auth.js

@@ -0,0 +1,111 @@
+import { normalizeBaseURL } from './cli-session.js';
+/** RFC 8628 device-authorization grant type. */
+const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const joinUrl = (base, path) => `${base}${path.startsWith('/') ? '' : '/'}${path}`;
+/**
+ * Run the better-auth device-authorization flow against `baseURL` and return a
+ * persisted-shaped session (token + best-effort expiry/user). The human
+ * approves in the browser; this only requests a code and polls for the token.
+ */
+export const deviceLogin = async (opts) => {
+    const baseURL = normalizeBaseURL(opts.baseURL);
+    const authBase = `${baseURL}${opts.authBasePath ?? '/auth'}`;
+    const clientId = opts.clientId ?? 'pikku-cli';
+    // 1. Request a device + user code.
+    const codeRes = await fetch(joinUrl(authBase, '/device/code'), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ client_id: clientId, scope: opts.scope }),
+    });
+    if (!codeRes.ok) {
+        throw new Error(`device/code failed (${codeRes.status}): ${await codeRes.text()}`);
+    }
+    const code = (await codeRes.json());
+    const expiresAtMs = Date.now() + code.expires_in * 1000;
+    await opts.onPrompt({
+        verificationUri: code.verification_uri,
+        verificationUriComplete: code.verification_uri_complete,
+        userCode: code.user_code,
+        expiresAtMs,
+    });
+    // 2. Poll the token endpoint until approved, denied, or expired.
+    let intervalMs = Math.max(1, code.interval) * 1000;
+    while (Date.now() < expiresAtMs) {
+        await sleep(intervalMs);
+        const tokenRes = await fetch(joinUrl(authBase, '/device/token'), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                grant_type: DEVICE_GRANT_TYPE,
+                device_code: code.device_code,
+                client_id: clientId,
+            }),
+        });
+        const body = (await tokenRes.json().catch(() => ({})));
+        if (tokenRes.ok && 'access_token' in body && body.access_token) {
+            return finalizeSession(baseURL, authBase, body);
+        }
+        const error = body.error;
+        if (error === 'authorization_pending') {
+            continue;
+        }
+        if (error === 'slow_down') {
+            // Back off as the spec requires.
+            intervalMs += 5000;
+            continue;
+        }
+        if (error === 'access_denied') {
+            throw new Error('Login was denied in the browser.');
+        }
+        if (error === 'expired_token') {
+            break;
+        }
+        // Unknown non-pending error — surface it rather than spinning.
+        throw new Error(`device/token failed (${tokenRes.status}): ${JSON.stringify(body)}`);
+    }
+    throw new Error('Login timed out before it was approved.');
+};
+/**
+ * Turn a token response into a stored session. Best-effort enriches it with the
+ * server-reported expiry + user by calling `/auth/get-session` with the bearer
+ * token (works when the `bearer` plugin is enabled); falls back to the token's
+ * own `expires_in` if that call is unavailable.
+ */
+const finalizeSession = async (baseURL, authBase, token) => {
+    const obtainedAt = new Date().toISOString();
+    let expiresAt;
+    let user;
+    if (typeof token.expires_in === 'number') {
+        expiresAt = new Date(Date.now() + token.expires_in * 1000).toISOString();
+    }
+    try {
+        const res = await fetch(joinUrl(authBase, '/get-session'), {
+            headers: { authorization: `Bearer ${token.access_token}` },
+        });
+        if (res.ok) {
+            const data = (await res.json());
+            if (data?.session?.expiresAt) {
+                expiresAt = new Date(data.session.expiresAt).toISOString();
+            }
+            if (data?.user) {
+                user = {
+                    id: data.user.id,
+                    email: data.user.email,
+                    name: data.user.name,
+                };
+            }
+        }
+    }
+    catch {
+        // get-session not reachable — keep whatever expiry we already have.
+    }
+    return {
+        baseURL,
+        accessToken: token.access_token,
+        tokenType: token.token_type ?? 'Bearer',
+        expiresAt,
+        user,
+        obtainedAt,
+    };
+};

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../bin/pikku.ts","../src/cli.wiring.ts","../src/services.ts","../src/deploy/build-pipeline.ts","../src/deploy/provider-adapter.ts","../src/deploy/server-entry.ts","../src/deploy/analyzer/analyzer.ts","../src/deploy/analyzer/index.ts","../src/deploy/analyzer/manifest.ts","../src/deploy/bundler/bundler.ts","../src/deploy/bundler/dep-extractor.ts","../src/deploy/bundler/index.ts","../src/deploy/bundler/types.ts","../src/deploy/codegen/index.ts","../src/deploy/codegen/per-unit-codegen.ts","../src/deploy/plan/executor.ts","../src/deploy/plan/formatter.ts","../src/deploy/plan/index.ts","../src/deploy/plan/planner.ts","../src/deploy/plan/provider.ts","../src/deploy/plan/types.ts","../src/fabric/fabric-commands.ts","../src/fabric/functions/db-schema.function.ts","../src/fabric/functions/deploy-list.function.ts","../src/fabric/functions/deploy-units.function.ts","../src/fabric/functions/deploy.function.ts","../src/fabric/functions/domains-add.function.ts","../src/fabric/functions/domains-list.function.ts","../src/fabric/functions/domains-remove.function.ts","../src/fabric/functions/errors.function.ts","../src/fabric/functions/init.function.ts","../src/fabric/functions/link.function.ts","../src/fabric/functions/llm-key.function.ts","../src/fabric/functions/login.function.ts","../src/fabric/functions/logs.function.ts","../src/fabric/functions/metrics.function.ts","../src/fabric/functions/rollback.function.ts","../src/fabric/functions/secrets-list.function.ts","../src/fabric/functions/secrets-set.function.ts","../src/fabric/functions/status.function.ts","../src/fabric/functions/trace.function.ts","../src/fabric/functions/validate-core.ts","../src/fabric/functions/validate.function.ts","../src/fabric/lib/config.ts","../src/fabric/lib/console-url.ts","../src/fabric/lib/git.ts","../src/fabric/lib/http.ts","../src/fabric/lib/not-implemented.ts","../src/fabric/lib/output.ts","../src/fabric/lib/prompt.ts","../src/fabric/lib/stage.ts","../src/fabric/sdk/http-map.gen.d.ts","../src/fabric/sdk/pikku-fetch.gen.ts","../src/fabric/sdk/pikku-rpc.gen.ts","../src/fabric/sdk/rpc-map.gen.d.ts","../src/functions/commands/all.ts","../src/functions/commands/binary.ts","../src/functions/commands/bootstrap.ts","../src/functions/commands/console.ts","../src/functions/commands/db-audit.ts","../src/functions/commands/db-generate.ts","../src/functions/commands/db-migrate.ts","../src/functions/commands/db-reset.ts","../src/functions/commands/db-seed.ts","../src/functions/commands/db-shared.ts","../src/functions/commands/deploy-apply.ts","../src/functions/commands/deploy-info.ts","../src/functions/commands/deploy-plan.ts","../src/functions/commands/dev.ts","../src/functions/commands/emails-init.ts","../src/functions/commands/enable.ts","../src/functions/commands/info.ts","../src/functions/commands/load-user-project.ts","../src/functions/commands/meta.ts","../src/functions/commands/new-addon.ts","../src/functions/commands/new-function.ts","../src/functions/commands/new-middleware.ts","../src/functions/commands/new-permission.ts","../src/functions/commands/new-wiring.ts","../src/functions/commands/pikku-command-bootstrap.ts","../src/functions/commands/pikku-command-summary.ts","../src/functions/commands/skills.ts","../src/functions/commands/tests-coverage.ts","../src/functions/commands/tests-init.ts","../src/functions/commands/versions-check.ts","../src/functions/commands/versions-init.ts","../src/functions/commands/versions-update.ts","../src/functions/commands/watch.ts","../src/functions/commands/workspace-validate.ts","../src/functions/db/annotation-parser.ts","../src/functions/db/better-auth-schema.ts","../src/functions/db/coercion-plugin.ts","../src/functions/db/db-codegen.ts","../src/functions/db/db-introspector.ts","../src/functions/db/db-migrator.ts","../src/functions/db/local-db.ts","../src/functions/db/zod-codegen.ts","../src/functions/db/postgres/postgres-introspector.ts","../src/functions/db/postgres/postgres-migrator.ts","../src/functions/db/sqlite/seed.ts","../src/functions/db/sqlite/sqlite-introspector.ts","../src/functions/db/sqlite/sqlite-kysely.ts","../src/functions/db/sqlite/sqlite-migrator.ts","../src/functions/db/sqlite/sqlite-runtime-bun.ts","../src/functions/db/sqlite/sqlite-runtime-node.ts","../src/functions/db/sqlite/sqlite-runtime.ts","../src/functions/runtimes/fetch/index.ts","../src/functions/runtimes/nextjs/pikku-command-nextjs.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-worker-rpc-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-http-wrapper.ts","../src/functions/runtimes/tanstack-start/pikku-command-tanstack-start.ts","../src/functions/runtimes/tanstack-start/serialize-tanstack-start-shim.ts","../src/functions/runtimes/websocket/pikku-command-websocket-typed.ts","../src/functions/runtimes/websocket/serialize-websocket-wrapper.ts","../src/functions/validate/workspace-validate.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent-types.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent.ts","../src/functions/wirings/ai-agent/pikku-command-public-agent.ts","../src/functions/wirings/ai-agent/serialize-agent-map.ts","../src/functions/wirings/ai-agent/serialize-ai-agent-types.ts","../src/functions/wirings/ai-agent/serialize-public-agent.ts","../src/functions/wirings/auth/pikku-command-auth.ts","../src/functions/wirings/auth/serialize-auth-gen.ts","../src/functions/wirings/auth/serialize-auth-meta.ts","../src/functions/wirings/auth/serialize-auth-types.ts","../src/functions/wirings/channels/pikku-channels.ts","../src/functions/wirings/channels/pikku-command-channel-types.ts","../src/functions/wirings/channels/pikku-command-channels-map.ts","../src/functions/wirings/channels/pikku-command-channels.ts","../src/functions/wirings/channels/serialize-channel-types.ts","../src/functions/wirings/channels/serialize-typed-channel-map.ts","../src/functions/wirings/cli/pikku-command-cli-entry.ts","../src/functions/wirings/cli/pikku-command-cli-types.ts","../src/functions/wirings/cli/pikku-command-cli.ts","../src/functions/wirings/cli/serialize-channel-cli-client.ts","../src/functions/wirings/cli/serialize-channel-cli.ts","../src/functions/wirings/cli/serialize-cli-types.ts","../src/functions/wirings/cli/serialize-local-cli-bootstrap.ts","../src/functions/wirings/console/pikku-command-console-functions.ts","../src/functions/wirings/console/pikku-command-node-types.ts","../src/functions/wirings/console/pikku-command-nodes-meta.ts","../src/functions/wirings/console/serialize-console-functions.ts","../src/functions/wirings/console/serialize-node-types.ts","../src/functions/wirings/credentials/pikku-command-credentials.ts","../src/functions/wirings/credentials/serialize-credentials-types.ts","../src/functions/wirings/emails/pikku-command-emails.ts","../src/functions/wirings/emails/serialize-emails.ts","../src/functions/wirings/functions/pikku-command-addon-types.ts","../src/functions/wirings/functions/pikku-command-function-types-split.ts","../src/functions/wirings/functions/pikku-command-function-types.ts","../src/functions/wirings/functions/pikku-command-functions.ts","../src/functions/wirings/functions/pikku-command-services.ts","../src/functions/wirings/functions/schemas.ts","../src/functions/wirings/functions/serialize-addon-types.ts","../src/functions/wirings/functions/serialize-function-imports.ts","../src/functions/wirings/functions/serialize-function-types.ts","../src/functions/wirings/functions/serialize-pikku-types-hub.ts","../src/functions/wirings/gateway/pikku-command-gateway.ts","../src/functions/wirings/http/pikku-command-http-map.ts","../src/functions/wirings/http/pikku-command-http-routes.ts","../src/functions/wirings/http/pikku-command-http-types.ts","../src/functions/wirings/http/pikku-command-openapi.ts","../src/functions/wirings/http/pikku-http-routes.ts","../src/functions/wirings/http/serialize-fetch-wrapper.ts","../src/functions/wirings/http/serialize-http-types.ts","../src/functions/wirings/http/serialize-typed-http-map.ts","../src/functions/wirings/mcp/pikku-command-mcp-json.ts","../src/functions/wirings/mcp/pikku-command-mcp-types.ts","../src/functions/wirings/mcp/pikku-command-mcp.ts","../src/functions/wirings/mcp/serialize-mcp-types.ts","../src/functions/wirings/middleware/pikku-command-middleware.ts","../src/functions/wirings/middleware/serialize-middleware-imports.ts","../src/functions/wirings/package/pikku-command-package-types.ts","../src/functions/wirings/package/pikku-command-package.ts","../src/functions/wirings/package/serialize-package-types.ts","../src/functions/wirings/package/serialize-package.ts","../src/functions/wirings/permissions/pikku-command-permissions.ts","../src/functions/wirings/permissions/serialize-permissions-imports.ts","../src/functions/wirings/queue/pikku-command-queue-map.ts","../src/functions/wirings/queue/pikku-command-queue-service.ts","../src/functions/wirings/queue/pikku-command-queue-types.ts","../src/functions/wirings/queue/pikku-command-queue.ts","../src/functions/wirings/queue/pikku-queue-map.ts","../src/functions/wirings/queue/pikku-queue.ts","../src/functions/wirings/queue/serialize-queue-map.ts","../src/functions/wirings/queue/serialize-queue-meta.ts","../src/functions/wirings/queue/serialize-queue-types.ts","../src/functions/wirings/queue/serialize-queue-wrapper.ts","../src/functions/wirings/realtime/pikku-command-events-scaffold.ts","../src/functions/wirings/realtime/pikku-command-realtime.ts","../src/functions/wirings/realtime/serialize-events-scaffold.ts","../src/functions/wirings/realtime/serialize-realtime-client.ts","../src/functions/wirings/rpc/pikku-command-public-rpc.ts","../src/functions/wirings/rpc/pikku-command-react-query.ts","../src/functions/wirings/rpc/pikku-command-remote-rpc.ts","../src/functions/wirings/rpc/pikku-command-rpc-client.ts","../src/functions/wirings/rpc/pikku-command-rpc-map.ts","../src/functions/wirings/rpc/pikku-command-rpc.ts","../src/functions/wirings/rpc/serialize-public-rpc.ts","../src/functions/wirings/rpc/serialize-react-query-hooks.ts","../src/functions/wirings/rpc/serialize-remote-rpc.ts","../src/functions/wirings/rpc/serialize-rpc-wrapper.ts","../src/functions/wirings/rpc/serialize-typed-rpc-map.ts","../src/functions/wirings/scheduler/pikku-command-scheduler-types.ts","../src/functions/wirings/scheduler/pikku-command-scheduler.ts","../src/functions/wirings/scheduler/serialize-scheduler-meta.ts","../src/functions/wirings/scheduler/serialize-scheduler-types.ts","../src/functions/wirings/secrets/pikku-command-secrets.ts","../src/functions/wirings/secrets/serialize-secrets-types.ts","../src/functions/wirings/triggers/pikku-command-trigger-types.ts","../src/functions/wirings/triggers/pikku-command-trigger.ts","../src/functions/wirings/triggers/serialize-trigger-meta.ts","../src/functions/wirings/triggers/serialize-trigger-types.ts","../src/functions/wirings/variables/pikku-command-variables.ts","../src/functions/wirings/variables/serialize-variables-types.ts","../src/functions/wirings/workflow/pikku-command-workflow-routes.ts","../src/functions/wirings/workflow/pikku-command-workflow.ts","../src/functions/wirings/workflow/serialize-workflow-bootstrap-map.ts","../src/functions/wirings/workflow/serialize-workflow-map.ts","../src/functions/wirings/workflow/serialize-workflow-meta.ts","../src/functions/wirings/workflow/serialize-workflow-registration.ts","../src/functions/wirings/workflow/serialize-workflow-routes.ts","../src/functions/wirings/workflow/serialize-workflow-types.ts","../src/functions/workflows/all.workflow.ts","../src/middleware/log-command-info-and-time.ts","../src/scaffold/rpc-remote.gen.ts","../src/services/cli-logger-forwarder.service.ts","../src/services/cli-logger.service.ts","../src/utils/check-required-types.ts","../src/utils/command-summary.ts","../src/utils/contract-versions.ts","../src/utils/file-import-path.ts","../src/utils/file-imports-serializer.ts","../src/utils/file-writer.ts","../src/utils/generate-bootstrap-file.ts","../src/utils/get-cli-version.ts","../src/utils/parse-cli-filters.ts","../src/utils/pikku-cli-config.ts","../src/utils/pikku-files-and-methods.ts","../src/utils/serialize-import-map.ts","../src/utils/serialize-meta-ts.ts","../src/utils/serialize-schemas.ts","../src/utils/strip-verbose-meta.ts","../.pikku/pikku-bootstrap.gen.ts","../.pikku/pikku-meta-service.gen.ts","../.pikku/pikku-services.gen.ts","../.pikku/pikku-types.gen.ts","../.pikku/agent/pikku-agent-map.gen.d.ts","../.pikku/agent/pikku-agent-types.gen.ts","../.pikku/channel/pikku-channel-types.gen.ts","../.pikku/cli/pikku-cli-channel.ts","../.pikku/cli/pikku-cli-types.gen.ts","../.pikku/cli/pikku-cli-wirings-meta.gen.ts","../.pikku/cli/pikku-cli-wirings.gen.ts","../.pikku/cli/pikku-cli.gen.ts","../.pikku/console/pikku-node-types.gen.ts","../.pikku/function/pikku-function-types.gen.ts","../.pikku/function/pikku-functions-meta.gen.ts","../.pikku/function/pikku-functions.gen.ts","../.pikku/http/pikku-http-types.gen.ts","../.pikku/http/pikku-http-wirings-map.gen.d.ts","../.pikku/http/pikku-http-wirings-meta.gen.ts","../.pikku/http/pikku-http-wirings.gen.ts","../.pikku/mcp/pikku-mcp-types.gen.ts","../.pikku/node/pikku-node-types.gen.ts","../.pikku/queue/pikku-queue-types.gen.ts","../.pikku/queue/pikku-queue-workers-wirings-map.gen.d.ts","../.pikku/queue/pikku-queue-workers-wirings-meta.gen.ts","../.pikku/queue/pikku-queue-workers-wirings.gen.ts","../.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-map.internal.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-meta.internal.gen.ts","../.pikku/scheduler/pikku-scheduler-types.gen.ts","../.pikku/schemas/register.gen.ts","../.pikku/secrets/pikku-secret-types.gen.ts","../.pikku/secrets/pikku-secrets.gen.ts","../.pikku/trigger/pikku-trigger-types.gen.ts","../.pikku/variables/pikku-variable-types.gen.ts","../.pikku/variables/pikku-variables.gen.ts","../.pikku/workflow/pikku-workflow-map.gen.d.ts","../.pikku/workflow/pikku-workflow-types.gen.ts","../.pikku/workflow/pikku-workflow-wirings-meta.gen.ts","../.pikku/workflow/pikku-workflow-wirings.gen.ts","../types/application-types.d.ts","../types/bun-sqlite.d.ts","../types/config.d.ts"],"version":"5.9.3"}
+{"root":["../bin/pikku.ts","../src/cli.wiring.ts","../src/services.ts","../src/deploy/build-pipeline.ts","../src/deploy/provider-adapter.ts","../src/deploy/server-entry.ts","../src/deploy/analyzer/analyzer.ts","../src/deploy/analyzer/index.ts","../src/deploy/analyzer/manifest.ts","../src/deploy/bundler/bundler.ts","../src/deploy/bundler/dep-extractor.ts","../src/deploy/bundler/index.ts","../src/deploy/bundler/types.ts","../src/deploy/codegen/index.ts","../src/deploy/codegen/per-unit-codegen.ts","../src/deploy/plan/executor.ts","../src/deploy/plan/formatter.ts","../src/deploy/plan/index.ts","../src/deploy/plan/planner.ts","../src/deploy/plan/provider.ts","../src/deploy/plan/types.ts","../src/fabric/fabric-commands.ts","../src/fabric/functions/db-schema.function.ts","../src/fabric/functions/deploy-list.function.ts","../src/fabric/functions/deploy-units.function.ts","../src/fabric/functions/deploy.function.ts","../src/fabric/functions/domains-add.function.ts","../src/fabric/functions/domains-list.function.ts","../src/fabric/functions/domains-remove.function.ts","../src/fabric/functions/errors.function.ts","../src/fabric/functions/init.function.ts","../src/fabric/functions/link.function.ts","../src/fabric/functions/llm-key.function.ts","../src/fabric/functions/login.function.ts","../src/fabric/functions/logs.function.ts","../src/fabric/functions/metrics.function.ts","../src/fabric/functions/rollback.function.ts","../src/fabric/functions/secrets-list.function.ts","../src/fabric/functions/secrets-set.function.ts","../src/fabric/functions/status.function.ts","../src/fabric/functions/trace.function.ts","../src/fabric/functions/validate-core.ts","../src/fabric/functions/validate.function.ts","../src/fabric/lib/config.ts","../src/fabric/lib/console-url.ts","../src/fabric/lib/git.ts","../src/fabric/lib/http.ts","../src/fabric/lib/not-implemented.ts","../src/fabric/lib/output.ts","../src/fabric/lib/prompt.ts","../src/fabric/lib/stage.ts","../src/fabric/sdk/http-map.gen.d.ts","../src/fabric/sdk/pikku-fetch.gen.ts","../src/fabric/sdk/pikku-rpc.gen.ts","../src/fabric/sdk/rpc-map.gen.d.ts","../src/functions/commands/all.ts","../src/functions/commands/binary.ts","../src/functions/commands/bootstrap.ts","../src/functions/commands/console.ts","../src/functions/commands/db-audit.ts","../src/functions/commands/db-generate.ts","../src/functions/commands/db-migrate.ts","../src/functions/commands/db-reset.ts","../src/functions/commands/db-seed.ts","../src/functions/commands/db-shared.ts","../src/functions/commands/deploy-apply.ts","../src/functions/commands/deploy-info.ts","../src/functions/commands/deploy-plan.ts","../src/functions/commands/dev.ts","../src/functions/commands/emails-init.ts","../src/functions/commands/enable.ts","../src/functions/commands/info.ts","../src/functions/commands/load-user-project.ts","../src/functions/commands/login.ts","../src/functions/commands/meta.ts","../src/functions/commands/new-addon.ts","../src/functions/commands/new-function.ts","../src/functions/commands/new-middleware.ts","../src/functions/commands/new-permission.ts","../src/functions/commands/new-wiring.ts","../src/functions/commands/pikku-command-bootstrap.ts","../src/functions/commands/pikku-command-summary.ts","../src/functions/commands/skills.ts","../src/functions/commands/tests-coverage.ts","../src/functions/commands/tests-init.ts","../src/functions/commands/versions-check.ts","../src/functions/commands/versions-init.ts","../src/functions/commands/versions-update.ts","../src/functions/commands/watch.ts","../src/functions/commands/workspace-validate.ts","../src/functions/db/annotation-parser.ts","../src/functions/db/better-auth-schema.ts","../src/functions/db/coercion-plugin.ts","../src/functions/db/db-codegen.ts","../src/functions/db/db-introspector.ts","../src/functions/db/db-migrator.ts","../src/functions/db/local-db.ts","../src/functions/db/zod-codegen.ts","../src/functions/db/postgres/pglite-kysely.ts","../src/functions/db/postgres/postgres-introspector.ts","../src/functions/db/postgres/postgres-migrator.ts","../src/functions/db/sqlite/seed.ts","../src/functions/db/sqlite/sqlite-introspector.ts","../src/functions/db/sqlite/sqlite-kysely.ts","../src/functions/db/sqlite/sqlite-migrator.ts","../src/functions/db/sqlite/sqlite-runtime-bun.ts","../src/functions/db/sqlite/sqlite-runtime-node.ts","../src/functions/db/sqlite/sqlite-runtime.ts","../src/functions/runtimes/fetch/index.ts","../src/functions/runtimes/nextjs/pikku-command-nextjs.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-worker-rpc-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-http-wrapper.ts","../src/functions/runtimes/tanstack-start/pikku-command-tanstack-start.ts","../src/functions/runtimes/tanstack-start/serialize-tanstack-start-shim.ts","../src/functions/runtimes/websocket/pikku-command-websocket-typed.ts","../src/functions/runtimes/websocket/serialize-websocket-wrapper.ts","../src/functions/validate/workspace-validate.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent-types.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent.ts","../src/functions/wirings/ai-agent/pikku-command-public-agent.ts","../src/functions/wirings/ai-agent/serialize-agent-map.ts","../src/functions/wirings/ai-agent/serialize-ai-agent-types.ts","../src/functions/wirings/ai-agent/serialize-public-agent.ts","../src/functions/wirings/auth/pikku-command-auth.ts","../src/functions/wirings/auth/serialize-auth-gen.ts","../src/functions/wirings/auth/serialize-auth-meta.ts","../src/functions/wirings/auth/serialize-auth-types.ts","../src/functions/wirings/channels/pikku-channels.ts","../src/functions/wirings/channels/pikku-command-channel-types.ts","../src/functions/wirings/channels/pikku-command-channels-map.ts","../src/functions/wirings/channels/pikku-command-channels.ts","../src/functions/wirings/channels/serialize-channel-types.ts","../src/functions/wirings/channels/serialize-typed-channel-map.ts","../src/functions/wirings/cli/pikku-command-cli-entry.ts","../src/functions/wirings/cli/pikku-command-cli-types.ts","../src/functions/wirings/cli/pikku-command-cli.ts","../src/functions/wirings/cli/serialize-channel-cli-client.ts","../src/functions/wirings/cli/serialize-channel-cli.ts","../src/functions/wirings/cli/serialize-cli-types.ts","../src/functions/wirings/cli/serialize-local-cli-bootstrap.ts","../src/functions/wirings/console/pikku-command-console-functions.ts","../src/functions/wirings/console/pikku-command-node-types.ts","../src/functions/wirings/console/pikku-command-nodes-meta.ts","../src/functions/wirings/console/serialize-console-functions.ts","../src/functions/wirings/console/serialize-node-types.ts","../src/functions/wirings/credentials/pikku-command-credentials.ts","../src/functions/wirings/credentials/serialize-credentials-types.ts","../src/functions/wirings/emails/pikku-command-emails.ts","../src/functions/wirings/emails/serialize-emails.ts","../src/functions/wirings/functions/pikku-command-addon-types.ts","../src/functions/wirings/functions/pikku-command-function-types-split.ts","../src/functions/wirings/functions/pikku-command-function-types.ts","../src/functions/wirings/functions/pikku-command-functions.ts","../src/functions/wirings/functions/pikku-command-services.ts","../src/functions/wirings/functions/schemas.ts","../src/functions/wirings/functions/serialize-addon-types.ts","../src/functions/wirings/functions/serialize-function-imports.ts","../src/functions/wirings/functions/serialize-function-types.ts","../src/functions/wirings/functions/serialize-pikku-types-hub.ts","../src/functions/wirings/gateway/pikku-command-gateway.ts","../src/functions/wirings/http/pikku-command-http-map.ts","../src/functions/wirings/http/pikku-command-http-routes.ts","../src/functions/wirings/http/pikku-command-http-types.ts","../src/functions/wirings/http/pikku-command-openapi.ts","../src/functions/wirings/http/pikku-http-routes.ts","../src/functions/wirings/http/serialize-fetch-wrapper.ts","../src/functions/wirings/http/serialize-http-types.ts","../src/functions/wirings/http/serialize-typed-http-map.ts","../src/functions/wirings/mcp/pikku-command-mcp-json.ts","../src/functions/wirings/mcp/pikku-command-mcp-types.ts","../src/functions/wirings/mcp/pikku-command-mcp.ts","../src/functions/wirings/mcp/serialize-mcp-types.ts","../src/functions/wirings/middleware/pikku-command-middleware.ts","../src/functions/wirings/middleware/serialize-middleware-imports.ts","../src/functions/wirings/package/pikku-command-package-types.ts","../src/functions/wirings/package/pikku-command-package.ts","../src/functions/wirings/package/serialize-package-types.ts","../src/functions/wirings/package/serialize-package.ts","../src/functions/wirings/permissions/pikku-command-permissions.ts","../src/functions/wirings/permissions/serialize-permissions-imports.ts","../src/functions/wirings/queue/pikku-command-queue-map.ts","../src/functions/wirings/queue/pikku-command-queue-service.ts","../src/functions/wirings/queue/pikku-command-queue-types.ts","../src/functions/wirings/queue/pikku-command-queue.ts","../src/functions/wirings/queue/pikku-queue-map.ts","../src/functions/wirings/queue/pikku-queue.ts","../src/functions/wirings/queue/serialize-queue-map.ts","../src/functions/wirings/queue/serialize-queue-meta.ts","../src/functions/wirings/queue/serialize-queue-types.ts","../src/functions/wirings/queue/serialize-queue-wrapper.ts","../src/functions/wirings/realtime/pikku-command-events-scaffold.ts","../src/functions/wirings/realtime/pikku-command-realtime.ts","../src/functions/wirings/realtime/serialize-events-scaffold.ts","../src/functions/wirings/realtime/serialize-realtime-client.ts","../src/functions/wirings/rpc/pikku-command-public-rpc.ts","../src/functions/wirings/rpc/pikku-command-react-query.ts","../src/functions/wirings/rpc/pikku-command-remote-rpc.ts","../src/functions/wirings/rpc/pikku-command-rpc-client.ts","../src/functions/wirings/rpc/pikku-command-rpc-map.ts","../src/functions/wirings/rpc/pikku-command-rpc.ts","../src/functions/wirings/rpc/serialize-public-rpc.ts","../src/functions/wirings/rpc/serialize-react-query-hooks.ts","../src/functions/wirings/rpc/serialize-remote-rpc.ts","../src/functions/wirings/rpc/serialize-rpc-wrapper.ts","../src/functions/wirings/rpc/serialize-typed-rpc-map.ts","../src/functions/wirings/scheduler/pikku-command-scheduler-types.ts","../src/functions/wirings/scheduler/pikku-command-scheduler.ts","../src/functions/wirings/scheduler/serialize-scheduler-meta.ts","../src/functions/wirings/scheduler/serialize-scheduler-types.ts","../src/functions/wirings/secrets/pikku-command-secrets.ts","../src/functions/wirings/secrets/serialize-secrets-types.ts","../src/functions/wirings/triggers/pikku-command-trigger-types.ts","../src/functions/wirings/triggers/pikku-command-trigger.ts","../src/functions/wirings/triggers/serialize-trigger-meta.ts","../src/functions/wirings/triggers/serialize-trigger-types.ts","../src/functions/wirings/variables/pikku-command-variables.ts","../src/functions/wirings/variables/serialize-variables-types.ts","../src/functions/wirings/workflow/pikku-command-workflow-routes.ts","../src/functions/wirings/workflow/pikku-command-workflow.ts","../src/functions/wirings/workflow/serialize-workflow-bootstrap-map.ts","../src/functions/wirings/workflow/serialize-workflow-map.ts","../src/functions/wirings/workflow/serialize-workflow-meta.ts","../src/functions/wirings/workflow/serialize-workflow-registration.ts","../src/functions/wirings/workflow/serialize-workflow-routes.ts","../src/functions/wirings/workflow/serialize-workflow-types.ts","../src/functions/workflows/all.workflow.ts","../src/middleware/log-command-info-and-time.ts","../src/scaffold/rpc-remote.gen.ts","../src/services/cli-logger-forwarder.service.ts","../src/services/cli-logger.service.ts","../src/utils/check-required-types.ts","../src/utils/cli-session.ts","../src/utils/command-summary.ts","../src/utils/contract-versions.ts","../src/utils/device-auth.ts","../src/utils/file-import-path.ts","../src/utils/file-imports-serializer.ts","../src/utils/file-writer.ts","../src/utils/generate-bootstrap-file.ts","../src/utils/get-cli-version.ts","../src/utils/parse-cli-filters.ts","../src/utils/pikku-cli-config.ts","../src/utils/pikku-files-and-methods.ts","../src/utils/serialize-import-map.ts","../src/utils/serialize-meta-ts.ts","../src/utils/serialize-schemas.ts","../src/utils/strip-verbose-meta.ts","../.pikku/pikku-bootstrap.gen.ts","../.pikku/pikku-meta-service.gen.ts","../.pikku/pikku-services.gen.ts","../.pikku/pikku-types.gen.ts","../.pikku/agent/pikku-agent-map.gen.d.ts","../.pikku/agent/pikku-agent-types.gen.ts","../.pikku/channel/pikku-channel-types.gen.ts","../.pikku/cli/pikku-cli-channel.ts","../.pikku/cli/pikku-cli-types.gen.ts","../.pikku/cli/pikku-cli-wirings-meta.gen.ts","../.pikku/cli/pikku-cli-wirings.gen.ts","../.pikku/cli/pikku-cli.gen.ts","../.pikku/console/pikku-node-types.gen.ts","../.pikku/function/pikku-function-types.gen.ts","../.pikku/function/pikku-functions-meta.gen.ts","../.pikku/function/pikku-functions.gen.ts","../.pikku/http/pikku-http-types.gen.ts","../.pikku/http/pikku-http-wirings-map.gen.d.ts","../.pikku/http/pikku-http-wirings-meta.gen.ts","../.pikku/http/pikku-http-wirings.gen.ts","../.pikku/mcp/pikku-mcp-types.gen.ts","../.pikku/node/pikku-node-types.gen.ts","../.pikku/queue/pikku-queue-types.gen.ts","../.pikku/queue/pikku-queue-workers-wirings-map.gen.d.ts","../.pikku/queue/pikku-queue-workers-wirings-meta.gen.ts","../.pikku/queue/pikku-queue-workers-wirings.gen.ts","../.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-map.internal.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-meta.internal.gen.ts","../.pikku/scheduler/pikku-scheduler-types.gen.ts","../.pikku/schemas/register.gen.ts","../.pikku/secrets/pikku-secret-types.gen.ts","../.pikku/secrets/pikku-secrets.gen.ts","../.pikku/trigger/pikku-trigger-types.gen.ts","../.pikku/variables/pikku-variable-types.gen.ts","../.pikku/variables/pikku-variables.gen.ts","../.pikku/workflow/pikku-workflow-map.gen.d.ts","../.pikku/workflow/pikku-workflow-types.gen.ts","../.pikku/workflow/pikku-workflow-wirings-meta.gen.ts","../.pikku/workflow/pikku-workflow-wirings.gen.ts","../types/application-types.d.ts","../types/bun-sqlite.d.ts","../types/config.d.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/cli",
-  "version": "0.12.39",
+  "version": "0.12.41",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "imports": {
@@ -25,9 +25,10 @@
     "prepublishOnly": "yarn build"
   },
   "dependencies": {
+    "@electric-sql/pglite": "^0.5.1",
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/better-auth": "^0.12.6",
-    "@pikku/core": "^0.12.32",
+    "@pikku/better-auth": "^0.12.7",
+    "@pikku/core": "^0.12.34",
     "@pikku/deploy-cloudflare": "^0.12.3",
     "@pikku/fetch": "^0.12.3",
     "@pikku/inspector": "^0.12.20",

package/skills/pikku-machine-auth/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: pikku-machine-auth
+description: 'Use when authenticating a CLI/agent/service against a Pikku server, adding machine-to-machine (M2M) auth, issuing scoped API keys for sandboxes/agents/workers, or wiring better-auth sessions into Pikku middleware. Covers `pikku login` (device-authorization), the better-auth API Key plugin, machine identities, and `betterAuthSession` with the api-key branch.
+TRIGGER when: user asks about CLI login, `pikku login`, machine agents, service-to-service auth, API keys, client credentials, sandbox/worker tokens, or resolving a better-auth session in a Pikku function.
+DO NOT TRIGGER when: user asks about end-user HTTP session/cookie auth only (use pikku-http + the app betterAuth config) or about WebSocket channel mechanics (use pikku-websocket).'
+---
+
+# Pikku Machine Auth
+
+Unified authentication for humans **and** machines against a Pikku + better-auth
+server. Two paths, two headers, one resolver:
+
+| Caller | Credential | Header | Obtained by |
+|---|---|---|---|
+| **Human** (CLI, dev) | better-auth session token | `Authorization: Bearer <token>` | `pikku login` (device flow) → `~/.pikku/session.json` |
+| **Machine** (agent, sandbox, worker) | scoped API key | `x-api-key: <key>` | `createApiKey` (server-side, at provision/spawn) |
+
+Both resolve to a Pikku `UserSession` through one middleware:
+`betterAuthSession({ mapSession, apiKey: { mapKey } })`.
+
+> The literal OAuth `client_credentials` grant is **not** implemented in
+> better-auth's oidc-provider. The API Key plugin gives the same capability (a
+> baked secret a service presents for scoped access), not the wire protocol.
+
+## Agent Operating Procedure
+
+1. Discover before editing — inspect the app's `betterAuth({ plugins: [...] })`
+   config and existing middleware wiring before adding anything.
+2. Server changes go in the auth factory + a middleware wiring file; never put
+   auth checks in a function body (use `permissions`).
+3. The API Key plugin contributes an `apikey` table — add the matching SQL
+   migration and regenerate DB types before relying on it.
+4. Validate with the narrowest command, then `pikku all`.
+
+## Human path — `pikku login`
+
+```bash
+pikku login --url https://app.example.com   # device-authorization flow
+pikku whoami                                  # show current session + expiry
+pikku logout                                  # remove stored session
+```
+
+`pikku login` runs the RFC 8628 device flow: it requests a code, opens the
+browser to the verification URL, polls until you approve, then stores the
+session token (keyed by base URL) at `~/.pikku/session.json` with its expiry.
+
+**Server requirement** — enable the `deviceAuthorization` and `bearer` plugins:
+
+```typescript
+import { deviceAuthorization, bearer } from 'better-auth/plugins'
+
+betterAuth({
+  // ...
+  plugins: [
+    deviceAuthorization({ expiresIn: '5min', interval: '5s', schema: {} }),
+    bearer(), // lets `Authorization: Bearer <session-token>` resolve a session
+  ],
+})
+```
+
+The browser approval is two steps the user's browser does automatically:
+`GET /auth/device?user_code=XXXX` (claims the code while signed in) then
+`POST /auth/device/approve`. The CLI only requests the code and polls
+`POST /auth/device/token`.
+
+## Machine path — API keys
+
+Install the plugin (separate official package) and enable it:
+
+```bash
+yarn add @better-auth/api-key   # peer: better-auth ^1.6.19
+```
+
+```typescript
+import { apiKey } from '@better-auth/api-key'
+
+betterAuth({
+  plugins: [
+    apiKey({
+      enableMetadata: true,          // REQUIRED to store scope on the key
+      enableSessionForAPIKeys: true, // lets a key resolve via getSession too
+    }),
+  ],
+})
+```
+
+### Identity model
+
+A **machine is an API key, not a throwaway user.** Keys are owned by a small set
+of stable **service-user** identities you provision once (e.g. `orchestrator`,
+`machine-agent`, `builder`, `sandbox-runtime`). Per-machine scope rides on the
+key's `metadata`/`permissions`. A key requires a real owning user row — minting
+one for a non-existent `userId` is created but will not resolve.
+
+### Mint a scoped key (server-side, at spawn/provision)
+
+```typescript
+// `auth` is the better-auth instance (injected service)
+const { key } = await auth.api.createApiKey({
+  body: {
+    userId: sandboxRuntimeUserId,        // a stable service user
+    name: `sandbox:${sandboxId}`,
+    expiresIn: 60 * 60,                   // seconds
+    metadata: { sandboxId },             // keep only STABLE ids here
+    permissions: { sandbox: ['read', 'write'] },
+  },
+})
+// inject `key` into the machine's env; it sends it as `x-api-key`.
+```
+
+Rotate by minting a new key and expiring/deleting the old (`deleteApiKey`);
+multiple active keys per identity allow zero-downtime rotation.
+
+### Resolve scope — `verifyApiKey`, not `getSession`
+
+`getSession(x-api-key)` returns only a bare mock session **without** the
+metadata. Scope must come from `verifyApiKey`, which returns
+`{ valid, key: { userId, metadata, permissions } }`. The
+`betterAuthSession` api-key branch does this for you:
+
+```typescript
+import { betterAuthSession } from '@pikku/better-auth'
+import { addHTTPMiddleware } from '@pikku/core/http'
+
+addHTTPMiddleware([
+  betterAuthSession({
+    // human path: getSession result -> app session
+    mapSession: ({ user }) => ({ userId: user.id }),
+    // machine path: verified key -> app session. `services` lets you resolve
+    // CURRENT scope (e.g. look up the owning row) instead of trusting only the
+    // baked metadata.
+    apiKey: {
+      header: 'x-api-key', // default
+      mapKey: async (key, services) => {
+        const sandboxId = key.metadata?.sandboxId
+        if (!sandboxId) return null // reject
+        const row = await services.kysely
+          .selectFrom('sandboxInstance')
+          .innerJoin('sandbox', 'sandbox.id', 'sandboxInstance.sandboxId')
+          .select(['sandbox.orgId', 'sandbox.projectId'])
+          .where('sandboxInstance.sandboxId', '=', sandboxId)
+          .where('sandboxInstance.stoppedAt', 'is', null)
+          .executeTakeFirst()
+        if (!row) return null
+        return { userId: sandboxId, orgId: row.orgId, role: 'sandbox' }
+      },
+    },
+  }),
+])
+```
+
+When the api-key header is present it is authoritative — the middleware never
+falls through to `getSession` (a bare mock session would shadow the scoped one).
+When it is absent, the human `getSession` path runs as normal.
+
+### WebSocket channels authenticate on the upgrade handshake
+
+Generated channel CLI clients attach the credential as a connection header
+(`x-api-key` for `PIKKU_API_KEY`, else `Authorization: Bearer` from
+`~/.pikku/session.json`). The `@pikku/ws` server copies the upgrade-request
+headers into the channel's `http.request` and runs the inherited HTTP `*`
+middleware during `runUpgradeMiddleware`, so `betterAuthSession` resolves the
+session before the channel opens. For this to work the app must register
+`betterAuthSession` via `addHTTPMiddleware([...])` (the `*` group) — not only on
+specific routes — so it is inherited into the channel upgrade. Browser clients
+cannot set WebSocket headers, so header-auth only covers the Node CLI path; a
+browser channel needs a query-param/subprotocol vector instead.
+
+## Gotchas
+
+- `apiKey()` rejects `metadata` unless `enableMetadata: true`.
+- `deviceAuthorization()` requires a `schema` option (pass `schema: {}`).
+- Keep the two paths on **different headers** — `x-api-key` (machine) vs
+  `Authorization: Bearer` (human). One header for both reintroduces ambiguity.
+- The `apikey` table is plugin-contributed — add the SQL migration + regen types.
+- `~/.pikku/session.json` is written `0600` and stores the token + expiry; the
+  CLI uses the expiry to detect when a re-login is needed.