@spekn/cli 1.0.0 → 1.0.2

package/dist/auth/device-flow.js

@@ -1,189 +0,0 @@
-"use strict";
-/**
- * RFC 8628 Device Authorization Grant (Device Flow)
- *
- * Implements the OAuth 2.0 Device Authorization Grant for CLI authentication
- * against a Keycloak realm.
- *
- * @see https://www.rfc-editor.org/rfc/rfc8628
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultOpenBrowser = void 0;
-exports.performDeviceFlow = performDeviceFlow;
-const zod_1 = require("zod");
-const DeviceAuthorizationResponseSchema = zod_1.z.object({
-    device_code: zod_1.z.string(),
-    user_code: zod_1.z.string(),
-    verification_uri: zod_1.z.string(),
-    verification_uri_complete: zod_1.z.string(),
-    expires_in: zod_1.z.number(),
-    interval: zod_1.z.number(),
-});
-const TokenSuccessResponseSchema = zod_1.z.object({
-    access_token: zod_1.z.string(),
-    refresh_token: zod_1.z.string(),
-    expires_in: zod_1.z.number(),
-    id_token: zod_1.z.string().optional(),
-    token_type: zod_1.z.string(),
-});
-const TokenErrorResponseSchema = zod_1.z.object({
-    error: zod_1.z.string(),
-    error_description: zod_1.z.string().optional(),
-});
-/** Default browser opener — dynamically imports the `open` package. */
-const defaultOpenBrowser = async (url) => {
-    const { default: open } = await Promise.resolve().then(() => __importStar(require("open")));
-    await open(url);
-};
-exports.defaultOpenBrowser = defaultOpenBrowser;
-const defaultDeps = {
-    stdout: process.stdout,
-    stderr: process.stderr,
-    openBrowser: defaultOpenBrowser,
-};
-/** Resolves deps, filling in defaults for any omitted fields. */
-function resolveDeps(deps) {
-    return {
-        stdout: deps?.stdout ?? defaultDeps.stdout,
-        stderr: deps?.stderr ?? defaultDeps.stderr,
-        openBrowser: deps?.openBrowser ?? defaultDeps.openBrowser,
-    };
-}
-/** Pause for `ms` milliseconds. */
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/**
- * Perform the RFC 8628 Device Authorization Grant against a Keycloak realm.
- *
- * @param keycloakUrl - Base Keycloak URL, e.g. `https://auth.example.com`
- * @param realm       - Keycloak realm name
- * @param clientId    - OAuth2 client ID (must be a public client)
- * @param deps        - Optional dependency overrides for testing / custom I/O
- * @returns Resolved tokens once the user authorises the device
- */
-async function performDeviceFlow(keycloakUrl, realm, clientId, deps) {
-    const { stdout, stderr, openBrowser } = resolveDeps(deps);
-    // -------------------------------------------------------------------------
-    // Step 1: Request device code
-    // -------------------------------------------------------------------------
-    const deviceAuthUrl = `${keycloakUrl}/realms/${realm}/protocol/openid-connect/auth/device`;
-    const deviceAuthBody = new URLSearchParams({
-        client_id: clientId,
-        scope: "openid email profile offline_access spekn-api",
-    });
-    const deviceAuthResponse = await fetch(deviceAuthUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: deviceAuthBody.toString(),
-    });
-    if (!deviceAuthResponse.ok) {
-        const text = await deviceAuthResponse.text();
-        throw new Error(`Device authorization request failed (${deviceAuthResponse.status}): ${text}`);
-    }
-    const deviceAuth = DeviceAuthorizationResponseSchema.parse(await deviceAuthResponse.json());
-    const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval, } = deviceAuth;
-    // -------------------------------------------------------------------------
-    // Step 2: Display instructions to the user
-    // -------------------------------------------------------------------------
-    stdout.write(`\nTo sign in, open this URL in your browser:\n` +
-        `  ${verification_uri_complete}\n\n` +
-        `Enter code: ${user_code}\n\n` +
-        `Waiting for authorization...\n`);
-    // -------------------------------------------------------------------------
-    // Step 3: Open browser (best-effort)
-    // -------------------------------------------------------------------------
-    try {
-        await openBrowser(verification_uri_complete);
-    }
-    catch (err) {
-        // Silently ignore browser-open failures; user still has the URL above.
-        const message = err instanceof Error ? err.message : String(err);
-        stderr.write(`(Could not open browser automatically: ${message})\n`);
-    }
-    // -------------------------------------------------------------------------
-    // Step 4: Poll token endpoint
-    // -------------------------------------------------------------------------
-    const tokenUrl = `${keycloakUrl}/realms/${realm}/protocol/openid-connect/token`;
-    const deadline = Date.now() + expires_in * 1000;
-    // RFC 8628 §3.5: default interval is 5 seconds when not specified.
-    let pollInterval = (interval ?? 5) * 1000;
-    while (Date.now() < deadline) {
-        await sleep(pollInterval);
-        const tokenBody = new URLSearchParams({
-            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
-            device_code,
-            client_id: clientId,
-        });
-        const tokenResponse = await fetch(tokenUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body: tokenBody.toString(),
-        });
-        if (tokenResponse.ok) {
-            // Success — return tokens.
-            const token = TokenSuccessResponseSchema.parse(await tokenResponse.json());
-            return {
-                accessToken: token.access_token,
-                refreshToken: token.refresh_token,
-                expiresIn: token.expires_in,
-                idToken: token.id_token,
-            };
-        }
-        // Non-200 responses carry an RFC 8628 error code in the JSON body.
-        const errorBody = TokenErrorResponseSchema.parse(await tokenResponse.json());
-        const errorCode = errorBody.error;
-        switch (errorCode) {
-            case "authorization_pending":
-                // User has not yet authorised — keep polling.
-                break;
-            case "slow_down":
-                // RFC 8628 §3.5: increase interval by 5 seconds and continue.
-                pollInterval += 5000;
-                break;
-            case "expired_token":
-                throw new Error("Device code expired. Please try again.");
-            case "access_denied":
-                throw new Error("Authorization denied by user.");
-            default:
-                throw new Error(`Unexpected token error "${errorCode}": ${errorBody.error_description ?? "no description"}`);
-        }
-    }
-    // -------------------------------------------------------------------------
-    // Step 5: Timeout — device code has expired without user action.
-    // -------------------------------------------------------------------------
-    throw new Error(`Authorization timed out after ${expires_in} seconds. Please try again.`);
-}

package/dist/auth/jwt.d.ts

@@ -1 +0,0 @@
-export { decodeJwtPayload, extractUserIdentity } from "@spekn/shared";

package/dist/auth/jwt.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractUserIdentity = exports.decodeJwtPayload = void 0;
-var shared_1 = require("@spekn/shared");
-Object.defineProperty(exports, "decodeJwtPayload", { enumerable: true, get: function () { return shared_1.decodeJwtPayload; } });
-Object.defineProperty(exports, "extractUserIdentity", { enumerable: true, get: function () { return shared_1.extractUserIdentity; } });

package/dist/auth/session.d.ts

@@ -1,67 +0,0 @@
-import type { CliCredentials } from "./credentials-store.js";
-import type { CredentialsStore } from "./credentials-store.js";
-import type { DeviceFlowDeps, DeviceFlowResult } from "./device-flow.js";
-interface BuildCredentialsInput {
-    result: DeviceFlowResult;
-    keycloakUrl: string;
-    realm: string;
-    organizationId?: string;
-}
-interface BuildCredentialsOutput {
-    credentials: CliCredentials;
-    user: {
-        sub: string;
-        email: string;
-        name?: string;
-    };
-}
-/**
- * Build persisted CLI credentials from a successful Keycloak device-flow result.
- */
-export declare function buildCredentialsFromDeviceFlow(input: BuildCredentialsInput): BuildCredentialsOutput;
-export interface EnsureAuthenticatedInput {
-    keycloakUrl: string;
-    realm: string;
-    credentialsStore: CredentialsStore;
-    performDeviceFlow: (keycloakUrl: string, realm: string, clientId: string, deps?: Partial<DeviceFlowDeps>) => Promise<DeviceFlowResult>;
-    stdout: {
-        write(s: string): void;
-    };
-    stderr: {
-        write(s: string): void;
-    };
-    forceDeviceFlow?: boolean;
-}
-export interface EnsureAuthenticatedResult {
-    accessToken: string;
-    credentials: CliCredentials;
-    user: {
-        sub: string;
-        email: string;
-        name?: string;
-    };
-    source: "existing" | "device_flow";
-}
-export interface ResolveOrganizationIdInput {
-    existingOrganizationId?: string;
-    envOrganizationId?: string;
-    fetchOrganizations: () => Promise<Array<{
-        id: string;
-        name: string;
-    }>>;
-    stdout?: {
-        write(s: string): void;
-    };
-}
-/**
- * Ensure CLI authentication is available.
- * - Reuses existing valid token by default.
- * - Runs device flow when forced or when no valid token exists.
- */
-export declare function ensureAuthenticated(input: EnsureAuthenticatedInput): Promise<EnsureAuthenticatedResult>;
-/**
- * Resolve effective organization context:
- * stored credentials first, then env, then API discovery fallback.
- */
-export declare function resolveOrganizationId(input: ResolveOrganizationIdInput): Promise<string | undefined>;
-export {};

package/dist/auth/session.js

@@ -1,86 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildCredentialsFromDeviceFlow = buildCredentialsFromDeviceFlow;
-exports.ensureAuthenticated = ensureAuthenticated;
-exports.resolveOrganizationId = resolveOrganizationId;
-const jwt_js_1 = require("./jwt.js");
-/**
- * Build persisted CLI credentials from a successful Keycloak device-flow result.
- */
-function buildCredentialsFromDeviceFlow(input) {
-    const claims = (0, jwt_js_1.decodeJwtPayload)(input.result.accessToken);
-    const user = (0, jwt_js_1.extractUserIdentity)(claims);
-    const credentials = {
-        accessToken: input.result.accessToken,
-        refreshToken: input.result.refreshToken,
-        expiresAt: Date.now() + input.result.expiresIn * 1000,
-        keycloakUrl: input.keycloakUrl,
-        realm: input.realm,
-        organizationId: input.organizationId,
-        user,
-    };
-    return { credentials, user };
-}
-/**
- * Ensure CLI authentication is available.
- * - Reuses existing valid token by default.
- * - Runs device flow when forced or when no valid token exists.
- */
-async function ensureAuthenticated(input) {
-    if (!input.forceDeviceFlow) {
-        const existingToken = await input.credentialsStore.getValidToken();
-        const existingCreds = input.credentialsStore.load();
-        if (existingToken && existingCreds) {
-            return {
-                accessToken: existingToken,
-                credentials: existingCreds,
-                user: existingCreds.user ?? {
-                    sub: "unknown",
-                    email: "unknown",
-                },
-                source: "existing",
-            };
-        }
-    }
-    const result = await input.performDeviceFlow(input.keycloakUrl, input.realm, "spekn-cli", { stdout: input.stdout, stderr: input.stderr });
-    const { credentials, user } = buildCredentialsFromDeviceFlow({
-        result,
-        keycloakUrl: input.keycloakUrl,
-        realm: input.realm,
-    });
-    input.credentialsStore.save(credentials);
-    return {
-        accessToken: result.accessToken,
-        credentials,
-        user,
-        source: "device_flow",
-    };
-}
-/**
- * Resolve effective organization context:
- * stored credentials first, then env, then API discovery fallback.
- */
-async function resolveOrganizationId(input) {
-    if (input.existingOrganizationId) {
-        return input.existingOrganizationId;
-    }
-    if (input.envOrganizationId) {
-        return input.envOrganizationId;
-    }
-    try {
-        const orgs = await input.fetchOrganizations();
-        if (orgs.length === 0)
-            return undefined;
-        if (orgs.length > 1 && input.stdout) {
-            input.stdout.write(`\nYou belong to ${orgs.length} organizations:\n`);
-            for (const org of orgs) {
-                input.stdout.write(`  - ${org.name} (${org.id})\n`);
-            }
-            input.stdout.write(`\nAuto-selected first organization. Use SPEKN_ORGANIZATION_ID to override.\n`);
-        }
-        return orgs[0]?.id;
-    }
-    catch {
-        return undefined;
-    }
-}

package/dist/auth-login.d.ts

@@ -1,34 +0,0 @@
-#!/usr/bin/env node
-/**
- * auth login CLI command
- *
- * Authenticates the CLI user via the Keycloak Device Authorization Grant
- * (RFC 8628) and persists credentials to ~/.spekn/credentials.json.
- *
- * Usage: spekn auth login [--keycloak-url <url>] [--realm <realm>]
- */
-import type { DeviceFlowDeps, DeviceFlowResult } from "./auth/device-flow.js";
-import { CredentialsStore } from "./auth/credentials-store.js";
-interface CLIOptions {
-    keycloakUrl: string;
-    realm: string;
-}
-interface Deps {
-    stdout: {
-        write(s: string): void;
-    };
-    stderr: {
-        write(s: string): void;
-    };
-    performDeviceFlow: (keycloakUrl: string, realm: string, clientId: string, deps?: Partial<DeviceFlowDeps>) => Promise<DeviceFlowResult>;
-    credentialsStore: CredentialsStore;
-}
-declare function parseArgs(args: string[]): CLIOptions;
-/**
- * Decode the payload of a JWT access token without verification.
- * Returns the raw claims object, or null if decoding fails.
- */
-declare function decodeJwtPayload(token: string): Record<string, unknown> | null;
-export declare function runAuthLoginCli(args: string[], deps?: Partial<Deps>): Promise<number>;
-declare function main(): Promise<void>;
-export { main, parseArgs, decodeJwtPayload };

package/dist/auth-login.js

@@ -1,202 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-/**
- * auth login CLI command
- *
- * Authenticates the CLI user via the Keycloak Device Authorization Grant
- * (RFC 8628) and persists credentials to ~/.spekn/credentials.json.
- *
- * Usage: spekn auth login [--keycloak-url <url>] [--realm <realm>]
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runAuthLoginCli = runAuthLoginCli;
-exports.main = main;
-exports.parseArgs = parseArgs;
-exports.decodeJwtPayload = decodeJwtPayload;
-const client_1 = require("@trpc/client");
-const device_flow_js_1 = require("./auth/device-flow.js");
-const credentials_store_js_1 = require("./auth/credentials-store.js");
-const help_error_1 = require("./utils/help-error");
-const trpc_url_1 = require("./utils/trpc-url");
-const structured_log_1 = require("./utils/structured-log");
-const defaultDeps = {
-    stdout: process.stdout,
-    stderr: process.stderr,
-    performDeviceFlow: device_flow_js_1.performDeviceFlow,
-    credentialsStore: new credentials_store_js_1.CredentialsStore(),
-};
-function resolveDeps(deps) {
-    return {
-        stdout: deps?.stdout ?? defaultDeps.stdout,
-        stderr: deps?.stderr ?? defaultDeps.stderr,
-        performDeviceFlow: deps?.performDeviceFlow ?? defaultDeps.performDeviceFlow,
-        credentialsStore: deps?.credentialsStore ?? defaultDeps.credentialsStore,
-    };
-}
-function printHelp(stderr) {
-    stderr.write(`
-auth login - Authenticate the Spekn CLI via browser-based device flow
-
-USAGE:
-  spekn auth login [options]
-
-OPTIONS:
-  --keycloak-url <url>   Keycloak base URL (default: KEYCLOAK_URL or https://auth.spekn.com)
-  --realm <realm>        Keycloak realm name (default: KEYCLOAK_REALM or spekn)
-  --help                 Show this help message
-
-ENVIRONMENT:
-  KEYCLOAK_URL           Keycloak base URL
-  KEYCLOAK_REALM         Keycloak realm name
-
-EXAMPLES:
-  spekn auth login
-  spekn auth login --keycloak-url https://auth.example.com --realm my-realm
-`);
-}
-function parseArgs(args) {
-    const keycloakUrlDefault = process.env["KEYCLOAK_URL"] ?? "https://auth.spekn.com";
-    const realmDefault = process.env["KEYCLOAK_REALM"] ?? "spekn";
-    let keycloakUrl = keycloakUrlDefault;
-    let realm = realmDefault;
-    for (let index = 0; index < args.length; index++) {
-        const arg = args[index];
-        if (arg === "--help" || arg === "-h") {
-            throw new help_error_1.HelpRequestedError();
-        }
-        if (arg === "--keycloak-url" && args[index + 1]) {
-            keycloakUrl = args[++index];
-            continue;
-        }
-        if (arg.startsWith("--keycloak-url=")) {
-            keycloakUrl = arg.slice("--keycloak-url=".length);
-            continue;
-        }
-        if (arg === "--realm" && args[index + 1]) {
-            realm = args[++index];
-            continue;
-        }
-        if (arg.startsWith("--realm=")) {
-            realm = arg.slice("--realm=".length);
-            continue;
-        }
-    }
-    return { keycloakUrl, realm };
-}
-/**
- * Decode the payload of a JWT access token without verification.
- * Returns the raw claims object, or null if decoding fails.
- */
-function decodeJwtPayload(token) {
-    try {
-        const parts = token.split(".");
-        if (parts.length !== 3) {
-            return null;
-        }
-        // Base64url → standard base64
-        const base64 = parts[1]
-            .replace(/-/g, "+")
-            .replace(/_/g, "/");
-        // Pad to a multiple of 4
-        const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
-        const json = Buffer.from(padded, "base64").toString("utf-8");
-        return JSON.parse(json);
-    }
-    catch {
-        return null;
-    }
-}
-async function runAuthLoginCli(args, deps) {
-    const resolved = resolveDeps(deps);
-    try {
-        const options = parseArgs(args);
-        (0, structured_log_1.appendCliStructuredLog)({
-            source: "cli.auth.login",
-            level: "info",
-            message: "Starting auth login",
-            details: { keycloakUrl: options.keycloakUrl, realm: options.realm },
-        });
-        const result = await resolved.performDeviceFlow(options.keycloakUrl, options.realm, "spekn-cli", { stdout: resolved.stdout, stderr: resolved.stderr });
-        // Decode the JWT payload to extract user identity fields.
-        const claims = decodeJwtPayload(result.accessToken);
-        const sub = typeof claims?.["sub"] === "string" ? claims["sub"] : "unknown";
-        const email = typeof claims?.["email"] === "string" ? claims["email"] : "unknown";
-        const name = typeof claims?.["name"] === "string"
-            ? claims["name"]
-            : typeof claims?.["preferred_username"] === "string"
-                ? claims["preferred_username"]
-                : undefined;
-        // Fetch the user's organizations from the API to resolve organizationId
-        const apiUrl = process.env.SPEKN_API_URL ?? "https://app.spekn.com";
-        const client = (0, client_1.createTRPCProxyClient)({
-            links: [
-                (0, client_1.httpBatchLink)({
-                    url: (0, trpc_url_1.normalizeTrpcUrl)(apiUrl),
-                    headers: {
-                        authorization: `Bearer ${result.accessToken}`,
-                    },
-                }),
-            ],
-        });
-        let organizationId;
-        try {
-            const orgs = await client.organization.list.query();
-            if (orgs.length === 1) {
-                organizationId = orgs[0].id;
-            }
-            else if (orgs.length > 1) {
-                resolved.stdout.write(`\nYou belong to ${orgs.length} organizations:\n`);
-                for (const org of orgs) {
-                    resolved.stdout.write(`  - ${org.name} (${org.id})\n`);
-                }
-                resolved.stdout.write(`\nAuto-selected first organization. Use SPEKN_ORGANIZATION_ID to override.\n`);
-                organizationId = orgs[0].id;
-            }
-        }
-        catch {
-            // Non-fatal — user can set SPEKN_ORGANIZATION_ID manually
-        }
-        const credentials = {
-            accessToken: result.accessToken,
-            refreshToken: result.refreshToken,
-            expiresAt: Date.now() + result.expiresIn * 1000,
-            keycloakUrl: options.keycloakUrl,
-            realm: options.realm,
-            organizationId,
-            user: { sub, email, name },
-        };
-        resolved.credentialsStore.save(credentials);
-        resolved.stdout.write(`Logged in as ${email}\n`);
-        if (organizationId) {
-            resolved.stdout.write(`Organization: ${organizationId}\n`);
-        }
-        (0, structured_log_1.appendCliStructuredLog)({
-            source: "cli.auth.login",
-            level: "info",
-            message: "Auth login completed",
-            details: { email, organizationId },
-        });
-        return 0;
-    }
-    catch (error) {
-        if (error instanceof help_error_1.HelpRequestedError) {
-            printHelp(resolved.stderr);
-            return 0;
-        }
-        const message = error instanceof Error ? error.message : String(error);
-        resolved.stderr.write(`Error: ${message}\n`);
-        (0, structured_log_1.appendCliStructuredLog)({
-            source: "cli.auth.login",
-            level: "error",
-            message,
-        });
-        return 1;
-    }
-}
-async function main() {
-    const exitCode = await runAuthLoginCli(process.argv.slice(2));
-    process.exit(exitCode);
-}
-if (require.main === module) {
-    void main();
-}

package/dist/auth-logout.d.ts

@@ -1,25 +0,0 @@
-#!/usr/bin/env node
-/**
- * auth logout CLI command
- *
- * Revokes the stored refresh token against Keycloak (best-effort) and then
- * removes the local credentials file at ~/.spekn/credentials.json.
- *
- * Usage: spekn auth logout
- */
-import { CredentialsStore } from "./auth/credentials-store.js";
-interface Deps {
-    stdout: {
-        write(s: string): void;
-    };
-    stderr: {
-        write(s: string): void;
-    };
-    credentialsStore: CredentialsStore;
-    /** POST to the Keycloak logout endpoint. Injected for testing. */
-    revokeToken: (logoutUrl: string, body: URLSearchParams) => Promise<void>;
-}
-declare function parseArgs(args: string[]): void;
-export declare function runAuthLogoutCli(args: string[], deps?: Partial<Deps>): Promise<number>;
-declare function main(): Promise<void>;
-export { main, parseArgs };