sandstream-kit 1.0.0

package/dist/documentation-generator.js

@@ -0,0 +1,348 @@
+import { IdGenerators } from "./id-generator.js";
+// ─── DocumentationGenerator ───────────────────────────────────────────────────
+export class DocumentationGenerator {
+    pages = new Map();
+    apiDocs = new Map();
+    examples = new Map();
+    tutorials = new Map();
+    collections = new Map();
+    searchIndex = new Map(); // term → pageIds
+    // ─── Page Management ──────────────────────────────────────────────────────
+    /**
+     * Create a documentation page.
+     */
+    createPage(title, content, type, author, tags = []) {
+        const id = IdGenerators.documentation();
+        const slug = title.toLowerCase().replace(/\s+/g, "-").replace(/[^\w-]/g, "");
+        const page = {
+            id,
+            title,
+            slug,
+            type,
+            content,
+            format: "markdown",
+            author,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            views: 0,
+            tags,
+            relatedPages: [],
+            toc: this.generateTableOfContents(content),
+        };
+        this.pages.set(id, page);
+        this.indexPage(id, content);
+        return page;
+    }
+    /**
+     * Get a page by ID.
+     */
+    getPage(pageId) {
+        const page = this.pages.get(pageId);
+        if (page) {
+            page.views++;
+        }
+        return page || null;
+    }
+    /**
+     * Update a page.
+     */
+    updatePage(pageId, updates) {
+        const page = this.pages.get(pageId);
+        if (!page)
+            return null;
+        Object.assign(page, updates, { updatedAt: new Date().toISOString() });
+        return page;
+    }
+    /**
+     * Delete a page.
+     */
+    deletePage(pageId) {
+        const page = this.pages.get(pageId);
+        if (!page)
+            return false;
+        // Remove from index
+        const terms = this.extractTerms(page.content);
+        for (const term of terms) {
+            this.searchIndex.get(term)?.delete(pageId);
+        }
+        this.pages.delete(pageId);
+        return true;
+    }
+    // ─── Table of Contents ────────────────────────────────────────────────────
+    /**
+     * Generate table of contents from markdown headings.
+     */
+    generateTableOfContents(content) {
+        const headings = [];
+        const lines = content.split("\n");
+        lines.forEach((line) => {
+            const match = line.match(/^(#+)\s+(.+)$/);
+            if (match) {
+                const level = match[1].length;
+                const title = match[2];
+                const id = title.toLowerCase().replace(/\s+/g, "-");
+                headings.push({ level, title, id });
+            }
+        });
+        return headings;
+    }
+    // ─── Search & Indexing ───────────────────────────────────────────────────
+    /**
+     * Index page content for full-text search.
+     */
+    indexPage(pageId, content) {
+        const terms = this.extractTerms(content);
+        for (const term of terms) {
+            const pages = this.searchIndex.get(term) || new Set();
+            pages.add(pageId);
+            this.searchIndex.set(term, pages);
+        }
+    }
+    /**
+     * Extract searchable terms from content.
+     */
+    extractTerms(content) {
+        return content
+            .toLowerCase()
+            .split(/\W+/)
+            .filter((term) => term.length > 2 && !this.isStopWord(term));
+    }
+    isStopWord(word) {
+        const stops = ["the", "and", "or", "is", "are", "was", "be", "to", "of", "in", "on", "at"];
+        return stops.includes(word);
+    }
+    /**
+     * Search documentation by keyword.
+     */
+    search(query, limit = 20) {
+        const terms = this.extractTerms(query);
+        const pageScores = new Map();
+        for (const term of terms) {
+            const pageIds = this.searchIndex.get(term) || new Set();
+            for (const pageId of pageIds) {
+                pageScores.set(pageId, (pageScores.get(pageId) || 0) + 1);
+            }
+        }
+        return [...pageScores.entries()]
+            .map(([pageId, score]) => {
+            const page = this.pages.get(pageId);
+            const snippet = this.extractSnippet(page.content, query, 150);
+            return { page, relevance: score, snippet };
+        })
+            .sort((a, b) => b.relevance - a.relevance)
+            .slice(0, limit);
+    }
+    /**
+     * Extract snippet around query term.
+     */
+    extractSnippet(content, query, length) {
+        const index = content.toLowerCase().indexOf(query.toLowerCase());
+        if (index === -1)
+            return content.substring(0, length) + "...";
+        const start = Math.max(0, index - length / 2);
+        const end = Math.min(content.length, start + length);
+        return (start > 0 ? "..." : "") + content.substring(start, end) + (end < content.length ? "..." : "");
+    }
+    // ─── API Documentation ───────────────────────────────────────────────────
+    /**
+     * Register API endpoint documentation.
+     */
+    registerAPIDoc(doc) {
+        this.apiDocs.set(doc.endpoint, doc);
+    }
+    /**
+     * Get API documentation for an endpoint.
+     */
+    getAPIDoc(endpoint) {
+        return this.apiDocs.get(endpoint) || null;
+    }
+    /**
+     * Get all API documentation.
+     */
+    getAllAPIDocsIndex() {
+        return [...this.apiDocs.values()];
+    }
+    /**
+     * Generate OpenAPI spec from registered endpoints.
+     */
+    generateOpenAPISpec(version = "3.0.0", baseUrl = "https://github.com/sandstream/kit") {
+        const paths = {};
+        for (const doc of this.apiDocs.values()) {
+            paths[doc.endpoint] = {
+                [doc.method.toLowerCase()]: {
+                    summary: doc.description,
+                    parameters: doc.parameters,
+                    responses: {
+                        200: {
+                            description: "Success",
+                            content: {
+                                "application/json": {
+                                    schema: doc.response,
+                                },
+                            },
+                        },
+                        ...Object.fromEntries(doc.errors.map((e) => [e.code, { description: e.message }])),
+                    },
+                },
+            };
+        }
+        return {
+            openapi: version,
+            info: { title: "kit Marketplace API", version },
+            servers: [{ url: baseUrl }],
+            paths,
+        };
+    }
+    // ─── Examples ────────────────────────────────────────────────────────────
+    /**
+     * Register a code example.
+     */
+    registerExample(example) {
+        this.examples.set(example.id, example);
+    }
+    /**
+     * Get example by ID.
+     */
+    getExample(exampleId) {
+        return this.examples.get(exampleId) || null;
+    }
+    /**
+     * Get examples by tag.
+     */
+    getExamplesByTag(tag) {
+        return [...this.examples.values()].filter((e) => e.tags.includes(tag));
+    }
+    /**
+     * Get examples by difficulty.
+     */
+    getExamplesByDifficulty(difficulty) {
+        return [...this.examples.values()].filter((e) => e.difficulty === difficulty);
+    }
+    // ─── Tutorials ───────────────────────────────────────────────────────────
+    /**
+     * Register a tutorial.
+     */
+    registerTutorial(tutorial) {
+        this.tutorials.set(tutorial.id, tutorial);
+    }
+    /**
+     * Get tutorial by ID.
+     */
+    getTutorial(tutorialId) {
+        return this.tutorials.get(tutorialId) || null;
+    }
+    /**
+     * Get tutorials by difficulty.
+     */
+    getTutorialsByDifficulty(difficulty) {
+        return [...this.tutorials.values()].filter((t) => t.difficulty === difficulty);
+    }
+    /**
+     * Get tutorials for beginners.
+     */
+    getBeginnerTutorials() {
+        return this.getTutorialsByDifficulty("beginner");
+    }
+    // ─── Collections ─────────────────────────────────────────────────────────
+    /**
+     * Create a documentation collection (category).
+     */
+    createCollection(category, description, pages, order = 0) {
+        const collection = {
+            category,
+            pages,
+            description,
+            order,
+        };
+        this.collections.set(category, collection);
+        return collection;
+    }
+    /**
+     * Get collection by category.
+     */
+    getCollection(category) {
+        return this.collections.get(category) || null;
+    }
+    /**
+     * Get all collections sorted by order.
+     */
+    getAllCollections() {
+        return [...this.collections.values()].sort((a, b) => a.order - b.order);
+    }
+    // ─── Export & Generation ─────────────────────────────────────────────────
+    /**
+     * Generate documentation HTML site structure.
+     */
+    generateSiteStructure() {
+        return {
+            collections: this.getAllCollections().map((col) => ({
+                name: col.category,
+                pages: col.pages.map((p) => ({
+                    title: p.title,
+                    slug: p.slug,
+                    type: p.type,
+                })),
+            })),
+        };
+    }
+    /**
+     * Generate a static site dump (markdown files).
+     */
+    generateMarkdownDump() {
+        const dump = {};
+        for (const page of this.pages.values()) {
+            const filename = `${page.slug}.md`;
+            dump[filename] = `# ${page.title}\n\n${page.content}`;
+        }
+        return dump;
+    }
+    /**
+     * Generate navigation sidebar structure.
+     */
+    generateNavigation() {
+        return this.getAllCollections().map((col) => ({
+            label: col.category,
+            items: col.pages.map((p) => ({
+                label: p.title,
+                href: `/docs/${p.slug}`,
+                type: p.type,
+            })),
+        }));
+    }
+    // ─── Statistics ───────────────────────────────────────────────────────────
+    /**
+     * Get documentation statistics.
+     */
+    getStats() {
+        const byType = {};
+        let totalLength = 0;
+        let totalViews = 0;
+        for (const page of this.pages.values()) {
+            byType[page.type] = (byType[page.type] || 0) + 1;
+            totalLength += page.content.length;
+            totalViews += page.views;
+        }
+        return {
+            totalPages: this.pages.size,
+            byType,
+            totalViews,
+            totalExamples: this.examples.size,
+            totalTutorials: this.tutorials.size,
+            avgPageLength: this.pages.size > 0 ? Math.round(totalLength / this.pages.size) : 0,
+        };
+    }
+    // ─── Cache helpers ────────────────────────────────────────────────────────
+    getPagesCache() {
+        return this.pages;
+    }
+    getExamplesCache() {
+        return this.examples;
+    }
+    getTutorialsCache() {
+        return this.tutorials;
+    }
+    getAPIDocsCache() {
+        return this.apiDocs;
+    }
+}
+//# sourceMappingURL=documentation-generator.js.map

package/dist/documentation-generator.js.map

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

package/dist/elevation-scopes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-operation elevation-scope mapping.
+ *
+ * `requireElevation("rotate")` is too coarse — it treats every rotate-mode
+ * the same. Some modes are reversible (scoped-key-mint with rollback),
+ * others are hard cutovers (jwt-secret-roll). This module maps each
+ * fine-grained operation to its canonical elevation-scope so the
+ * elevation-gate matches the destructive nature of the actual call.
+ *
+ * Mapping principles:
+ *   - Reversible ops → standard 15-min TTL scope (call `requireElevation`).
+ *   - Irreversible ops → one-shot scope (call `consumeElevation`); marker
+ *     is atomically deleted on use so the same elevation can't fire a
+ *     second destructive op silently.
+ *
+ * Callers ask `scopeFor(operation, mode)` to get the canonical scope name
+ * + whether it's one-shot. They never hard-code scope strings.
+ */
+export interface ElevationScopeMapping {
+    /** Canonical scope name passed to requireElevation / consumeElevation. */
+    scope: string;
+    /** One-shot scopes consume their elevation marker on first use. */
+    oneShot: boolean;
+    /** Human-readable description for audit-log + CLI help text. */
+    description: string;
+}
+export declare function scopeFor(operation: string, mode?: string): ElevationScopeMapping;
+/**
+ * Returns true when the (operation, mode) pair requires one-shot elevation.
+ * Convenience helper for callers that need to pick between requireElevation
+ * and consumeElevation at runtime.
+ */
+export declare function isOneShot(operation: string, mode?: string): boolean;
+/**
+ * Lists every mapping — used by `kit auth elevate --list-scopes` to
+ * surface what scopes are available + their one-shot status.
+ */
+export declare function listScopes(): Array<{
+    key: string;
+} & ElevationScopeMapping>;

package/dist/elevation-scopes.js

@@ -0,0 +1,110 @@
+/**
+ * Per-operation elevation-scope mapping.
+ *
+ * `requireElevation("rotate")` is too coarse — it treats every rotate-mode
+ * the same. Some modes are reversible (scoped-key-mint with rollback),
+ * others are hard cutovers (jwt-secret-roll). This module maps each
+ * fine-grained operation to its canonical elevation-scope so the
+ * elevation-gate matches the destructive nature of the actual call.
+ *
+ * Mapping principles:
+ *   - Reversible ops → standard 15-min TTL scope (call `requireElevation`).
+ *   - Irreversible ops → one-shot scope (call `consumeElevation`); marker
+ *     is atomically deleted on use so the same elevation can't fire a
+ *     second destructive op silently.
+ *
+ * Callers ask `scopeFor(operation, mode)` to get the canonical scope name
+ * + whether it's one-shot. They never hard-code scope strings.
+ */
+/**
+ * `<operation>:<mode>` → mapping. Operations like "rotate" have multiple
+ * modes; bare keys (no `:<mode>`) act as fallbacks.
+ */
+const SCOPE_MAP = {
+    // Rotation modes
+    "rotate:jwt-secret-roll": {
+        scope: "rotate",
+        oneShot: true,
+        description: "Supabase JWT-secret reset — invalidates anon + service_role + all sessions",
+    },
+    "rotate:scoped-key-mint": {
+        scope: "rotate",
+        oneShot: false,
+        description: "Supabase scoped-key mint — additive, old key remains until revoke-old",
+    },
+    rotate: {
+        scope: "rotate",
+        oneShot: false,
+        description: "Generic credential rotation",
+    },
+    // Migration
+    "migrate:plaintext-to-vault": {
+        scope: "migrate",
+        oneShot: false,
+        description: "Plaintext .env* → vault migration",
+    },
+    "migrate:vault-to-vault": {
+        scope: "vault-migrate",
+        oneShot: true,
+        description: "Cross-vault migration (e.g. 1Password → Infisical)",
+    },
+    migrate: {
+        scope: "migrate",
+        oneShot: false,
+        description: "Generic secret migration",
+    },
+    // Propagation
+    propagate: {
+        scope: "propagate",
+        oneShot: false,
+        description: "Sync secrets from kit to deploy platform (Vercel / Fly / etc.)",
+    },
+    // History rewrite — irreversible
+    "purge-history": {
+        scope: "purge-history",
+        oneShot: true,
+        description: "git filter-repo / BFG — rewrites history, requires force-push",
+    },
+    // OneCLI register
+    "onecli-register": {
+        scope: "onecli-register",
+        oneShot: true,
+        description: "Register fake-key in OneCLI gateway",
+    },
+    // Revoke
+    "revoke-old": {
+        scope: "revoke-old",
+        oneShot: false,
+        description: "Revoke superseded credential after rotation",
+    },
+};
+export function scopeFor(operation, mode) {
+    if (mode) {
+        const composite = `${operation}:${mode}`;
+        if (SCOPE_MAP[composite])
+            return SCOPE_MAP[composite];
+    }
+    if (SCOPE_MAP[operation])
+        return SCOPE_MAP[operation];
+    return {
+        scope: operation,
+        oneShot: false,
+        description: `Unmapped operation "${operation}" — using bare scope`,
+    };
+}
+/**
+ * Returns true when the (operation, mode) pair requires one-shot elevation.
+ * Convenience helper for callers that need to pick between requireElevation
+ * and consumeElevation at runtime.
+ */
+export function isOneShot(operation, mode) {
+    return scopeFor(operation, mode).oneShot;
+}
+/**
+ * Lists every mapping — used by `kit auth elevate --list-scopes` to
+ * surface what scopes are available + their one-shot status.
+ */
+export function listScopes() {
+    return Object.entries(SCOPE_MAP).map(([key, m]) => ({ key, ...m }));
+}
+//# sourceMappingURL=elevation-scopes.js.map

package/dist/elevation-scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elevation-scopes.js","sourceRoot":"","sources":["../src/elevation-scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH;;;GAGG;AACH,MAAM,SAAS,GAA0C;IACvD,iBAAiB;IACjB,wBAAwB,EAAE;QACxB,KAAK,EAAE,QAAQ;QACf,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,4EAA4E;KAC1F;IACD,wBAAwB,EAAE;QACxB,KAAK,EAAE,QAAQ;QACf,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,uEAAuE;KACrF;IACD,MAAM,EAAE;QACN,KAAK,EAAE,QAAQ;QACf,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,6BAA6B;KAC3C;IAED,YAAY;IACZ,4BAA4B,EAAE;QAC5B,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,mCAAmC;KACjD;IACD,wBAAwB,EAAE;QACxB,KAAK,EAAE,eAAe;QACtB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,oDAAoD;KAClE;IACD,OAAO,EAAE;QACP,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,0BAA0B;KACxC;IAED,cAAc;IACd,SAAS,EAAE;QACT,KAAK,EAAE,WAAW;QAClB,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,gEAAgE;KAC9E;IAED,iCAAiC;IACjC,eAAe,EAAE;QACf,KAAK,EAAE,eAAe;QACtB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,+DAA+D;KAC7E;IAED,kBAAkB;IAClB,iBAAiB,EAAE;QACjB,KAAK,EAAE,iBAAiB;QACxB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,qCAAqC;KACnD;IAED,SAAS;IACT,YAAY,EAAE;QACZ,KAAK,EAAE,YAAY;QACnB,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,6CAA6C;KAC3D;CACF,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,IAAa;IACvD,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,SAAS,GAAG,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC;QACzC,IAAI,SAAS,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,SAAS,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC,SAAS,CAAC,CAAC;IACtD,OAAO;QACL,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,uBAAuB,SAAS,sBAAsB;KACpE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,SAAiB,EAAE,IAAa;IACxD,OAAO,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/elevation.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Elevation gate for destructive secret operations.
+ *
+ * User requirement: agents (or unauthorized humans) must not be able to
+ * rotate / migrate / propagate / register-fake a key without an explicit
+ * human-loop confirmation. This module provides:
+ *
+ *   1. A short-lived elevation marker (`.kit/elevation.json`) with TTL,
+ *      created by `kit auth elevate`.
+ *   2. Optional TOTP (RFC 6238) verification when `KIT_TOTP_SECRET` is set.
+ *      Without TOTP, falls back to a plain interactive "YES" prompt.
+ *   3. A `requireElevation()` check that destructive ops call before running.
+ *      In non-interactive / agent contexts: fails closed unless
+ *      `KIT_ELEVATED=1` is set (CI escape hatch — gets audit-logged loudly
+ *      so a leaked CI env doesn't silently bypass).
+ */
+export declare function isOneShotScope(scope: string): boolean;
+export interface ElevationState {
+    expiresAt: string;
+    scope: string;
+    granter: string;
+    method: "yes-prompt" | "totp" | "ci-env";
+}
+export declare function readElevation(cwd?: string): Promise<ElevationState | null>;
+export declare function writeElevation(state: ElevationState, cwd?: string): Promise<void>;
+export declare function clearElevation(cwd?: string): Promise<void>;
+/**
+ * Returns true if an unexpired elevation marker exists that covers the
+ * requested operation scope.
+ */
+export declare function isElevated(operation: string, cwd?: string): Promise<boolean>;
+export declare function elevationTtlMinutes(): number;
+/**
+ * Mints a fresh elevation marker covering `scope` for the configured TTL.
+ * Caller is responsible for prompting / verifying the user before calling.
+ */
+export declare function grantElevation(scope: string, method: ElevationState["method"], cwd?: string, granter?: string): Promise<ElevationState>;
+export declare function generateBase32Secret(byteLength?: number): string;
+export interface OtpAuthUriInput {
+    /** Identifier shown in the authenticator app (typically user@host). */
+    accountName: string;
+    /** Top-level label of the entry — appears as section heading. */
+    issuer?: string;
+    /** Base32 secret. */
+    secret: string;
+}
+export declare function buildOtpAuthUri(input: OtpAuthUriInput): string;
+export interface EnrolledSecret {
+    secret: string;
+    filePath: string;
+    uri: string;
+    currentCode: string;
+}
+export declare function enrollTotp(opts: {
+    accountName: string;
+    issuer?: string;
+    overwrite?: boolean;
+}): Promise<EnrolledSecret>;
+/**
+ * Resolves the TOTP secret in priority order:
+ *   1. `KIT_TOTP_SECRET` env var (overrides everything; useful for CI)
+ *   2. `~/.kit/totp-secret` file (created by `kit auth setup-totp`)
+ *   3. undefined — caller falls back to yes-prompt
+ */
+export declare function resolveTotpSecret(): Promise<string | undefined>;
+export declare function generateTotp(secretBase32: string, step?: number): string;
+/**
+ * Verifies a user-supplied TOTP. Accepts the current step ± 1 (handles minor
+ * clock skew, ±30s window). Uses timingSafeEqual for the digit comparison —
+ * both sides are fixed 6-ASCII-digit strings, so lengths always match.
+ */
+export declare function verifyTotp(code: string, secretBase32: string, windowSteps?: number): boolean;
+/**
+ * Throws (or returns false in nice mode) when the active context isn't
+ * elevated for `operation`. Used by every destructive secrets-* command.
+ *
+ * Order of resolution:
+ *   1. `KIT_ELEVATED=1` env var (CI escape hatch).
+ *   2. A live elevation marker covering the operation.
+ *   3. Otherwise: not elevated.
+ *
+ * Every decision — granted or refused — emits an audit-log entry before
+ * returning. If the audit-log write itself fails, the call returns
+ * `{ ok: false }` even if the credential would otherwise be granted. The
+ * intent is: a code path that runs destructive ops must always leave a
+ * forensic trail; "audit-log down" is treated identically to "elevation
+ * refused" so the silent-bypass property is eliminated.
+ */
+export declare function requireElevation(operation: string, cwd?: string): Promise<{
+    ok: boolean;
+    reason: string;
+}>;
+export declare function consumeElevation(operation: string, cwd?: string): Promise<{
+    ok: boolean;
+    reason: string;
+}>;
+/**
+ * Test-only: reset the in-process consumed-scope set. Public so tests can
+ * exercise the one-shot semantics deterministically without spawning new
+ * processes.
+ */
+export declare function _resetConsumedElevationForTests(): void;