docugate 0.2.8 → 0.3.0

package/dist/init.js

@@ -1,12 +1,16 @@
 import { createInterface } from 'node:readline';
 import { execFileSync, spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { CONFIG_FILE, loadConfig } from './config.js';
+import { readText } from './text.js';
 import { tourInit, BobMissingError, BobKeyMissingError, readBobKey, useBobKeyForThisRun } from './tour-init.js';
 import { bobKeyCandidates, startSpinner } from './spinner.js';
+import { banner } from './banner.js';
 import { tourInstall, pillSnippetLine, DEFAULT_PORT } from './tour-install.js';
 import { login, loadCredentials } from './auth.js';
+export { asCommand } from './ui.js';
+import { asCommand } from './ui.js';
 /**
  * Sets a repository up for DocuGate: a docugate.json, and a first page if the
  * docs folder has none. Never overwrites — running it twice is harmless, and
@@ -69,10 +73,49 @@ export function makeDefaultIO() {
             });
         },
         print(line) {
-            console.log(line);
+            console.log(asCommand(line));
         },
     };
 }
+function gh(args, cwd = process.cwd()) {
+    try {
+        const out = execFileSync('gh', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+        return { ok: true, out: out.trim() };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, out: (e.stderr ?? e.message).trim() };
+    }
+}
+/**
+ * The docs repository through the GitHub CLI, signed in as the person: create
+ * it with a README, then write docs/index.md into it through the GitHub API.
+ * Null when gh is not installed or not signed in, with the reason printed.
+ */
+function createDocsRepoWithGh(name, isPrivate, title, io) {
+    const who = gh(['api', 'user', '--jq', '.login']);
+    if (!who.ok || !who.out) {
+        io.print(`  To create it another way, install the GitHub CLI (https://cli.github.com), run gh auth login, then docugate init again.`);
+        io.print(`  Or create ${name} on github.com and pick "connect" in docugate init.`);
+        return null;
+    }
+    const stop = startSpinner(['Creating the docs repository with the GitHub CLI', 'Writing its first page']);
+    const made = gh(['repo', 'create', name, isPrivate ? '--private' : '--public', '--add-readme',
+        '--description', `Documentation for ${title}, published with DocuGate`]);
+    if (!made.ok && !/already exists/i.test(made.out)) {
+        stop();
+        io.print(`  warning  The GitHub CLI could not create ${name}: ${made.out.split(/\r?\n/).pop()}`);
+        return null;
+    }
+    const full = `${who.out}/${name}`;
+    const page = `# ${title}\n\nWelcome. This is the start of the documentation for ${title}.\n\nEvery markdown file in this \`docs/\` folder becomes a page on DocuGate.\n`;
+    const seeded = gh(['api', '-X', 'PUT', `repos/${full}/contents/docs/index.md`,
+        '-f', 'message=docs: first page, created by DocuGate',
+        '-f', `content=${Buffer.from(page).toString('base64')}`]).ok;
+    stop();
+    io.print(`  ${green('✓')} Created https://github.com/${full} with the GitHub CLI`);
+    return { repo: full, url: `https://github.com/${full}`, cloneUrl: `https://github.com/${full}.git`, seeded };
+}
 /**
  * A new space and the repository that holds its docs: the repository is
  * created on the person's account with docs/index.md in it, then the space is
@@ -93,12 +136,36 @@ async function createDocsSpace(io, projectName, baseUrl, options) {
             return createRepo(name, priv, { title });
         }))(repoName, visibility === 2, projectName);
         stop();
-        io.print(`  Created ${repo.url}`);
+        io.print(`  ${green('✓')} Created ${repo.url}`);
     }
     catch (err) {
         stop();
-        io.print(`  warning  ${err.message}`);
-        return undefined;
+        const { code } = err;
+        // DocuGate could not create it (the app's permission, or GitHub's rules
+        // for app tokens). The person's own GitHub CLI can: try that before
+        // giving up, so the setup still ends with a space.
+        if (code === 'app_permission' || code === 'github_error') {
+            io.print(`  ${dimmed(err.message)}`);
+            repo = (options.ghDocsRepoFn ?? createDocsRepoWithGh)(repoName, visibility === 2, projectName, io) ?? undefined;
+        }
+        else if (code === 'repo_exists') {
+            // A second run, or a repository made by hand: use it rather than stop.
+            const login = await (options.getSessionFn ?? (async () => (await import('./api.js')).getSession()))()
+                .then((s) => s.user?.githubLogin)
+                .catch(() => undefined);
+            if (login) {
+                repo = { repo: `${login}/${repoName}`, url: `https://github.com/${login}/${repoName}`, cloneUrl: '' };
+                io.print(`  ${repo.repo} already exists: using it for the docs.`);
+            }
+            else {
+                io.print(`  warning  ${err.message}`);
+            }
+        }
+        else {
+            io.print(`  warning  ${err.message}`);
+        }
+        if (!repo)
+            return undefined;
     }
     const createFn = options.createSpaceFn ?? (async (r, name, dir) => {
         const { createSpace } = await import('./api.js');
@@ -151,17 +218,27 @@ export function setUpAbove(root) {
     }
     return undefined;
 }
-/** Sets one key in docugate.json, keeping everything else as it was. */
-function saveSetting(root, key, value) {
+/**
+ * Sets one key in docugate.json, keeping everything else as it was.
+ *
+ * A file that cannot be read is left alone and reported. It used to be started over with
+ * just this key, which threw away a hand-written `title` and `sidebar` over one stray comma.
+ */
+export function saveSetting(root, key, value) {
     const path = join(root, CONFIG_FILE);
     let existing = {};
     if (existsSync(path)) {
+        let parsed;
         try {
-            existing = JSON.parse(readFileSync(path, 'utf8'));
+            parsed = JSON.parse(readText(path));
         }
         catch {
-            // unreadable: start again with this key
+            parsed = undefined;
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`${CONFIG_FILE} is not valid JSON, so it was not changed. Fix it, or delete it, and run this again.`);
         }
+        existing = parsed;
     }
     existing[key] = value;
     writeFileSync(path, JSON.stringify(existing, null, 2) + '\n');
@@ -188,7 +265,9 @@ async function askForBobKey(io, openUrl) {
         return false;
     }
     useBobKeyForThisRun(key);
-    io.print('  Using the key for this run only. To keep it for next time, set it in your environment:');
+    // Say it arrived, without showing it: the last four characters and the length.
+    io.print(`  ${green('✓')} Key received (…${key.slice(-4)}, ${key.length} characters). Using it for this run only.`);
+    io.print('  To keep it for next time, set it in your environment:');
     io.print(process.platform === 'win32'
         ? '    [Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")   (then open a new terminal)'
         : '    export BOB_API_KEY=<key>   (add it to your shell profile)');
@@ -212,18 +291,7 @@ export const FRESHNESS = [
     { value: 'off', label: 'Never, I will ask for it' },
 ];
 function saveRole(root, role) {
-    const path = join(root, CONFIG_FILE);
-    let existing = {};
-    if (existsSync(path)) {
-        try {
-            existing = JSON.parse(readFileSync(path, 'utf8'));
-        }
-        catch {
-            // leave as empty object; will be overwritten with role added
-        }
-    }
-    existing.role = role;
-    writeFileSync(path, JSON.stringify(existing, null, 2) + '\n');
+    saveSetting(root, 'role', role);
 }
 const ROLE_CHOICES = [{ role: 'frontend' }, { role: 'backend' }, { role: 'both' }];
 const FRONTEND_DIRS = ['frontend', 'client', 'web'];
@@ -256,16 +324,6 @@ const dimmed = paint('2');
 const gold = paint('38;2;244;196;63');
 const cream = paint('38;2;245;240;227');
 const green = paint('32');
-/** DocuGate's owl, drawn small: cream eyes, gold beak. */
-export function banner() {
-    return [
-        '',
-        `   ${dimmed('╭─────╮')}`,
-        `   ${dimmed('│')} ${cream('◉ ◉')} ${dimmed('│')}   ${bold('DocuGate')}`,
-        `   ${dimmed('│')}  ${gold('▾')}  ${dimmed('│')}   ${dimmed('Tours and docs for your codebase')}`,
-        `   ${dimmed('╰─────╯')}`,
-    ];
-}
 /**
  * A numbered choice: prints the options, and takes only a number. Enter picks
  * the default. Nobody types a word during setup.
@@ -282,7 +340,7 @@ export async function choose(io, question, options, fallback = 1) {
         io.print(`  Type a number from 1 to ${options.length}.`);
     }
 }
-function defaultGetRemote(root) {
+export function defaultGetRemote(root) {
     try {
         const remote = execFileSync('git', ['remote', 'get-url', 'origin'], {
             encoding: 'utf8',
@@ -549,14 +607,14 @@ export async function initFlow(root, options = {}) {
             try {
                 tourResult = tourInit(root, { runBob: options.runBob });
                 stop();
-                io.print(`  IBM Bob wrote the tour.`);
+                io.print(`  ${green('✓')} IBM Bob wrote the tour (${tourResult.added.length} screen${tourResult.added.length === 1 ? '' : 's'}).`);
             }
             catch (error) {
                 stop();
                 // Bob missing or failed — describe what went wrong, then continue.
                 if (error instanceof BobKeyMissingError) {
                     tourError =
-                        `IBM Bob did not accept the key. Check BOB_API_KEY holds an Inference key from bob.ibm.com, then run docugate tour init.`;
+                        `✗ IBM Bob did not accept this key. Check it is an Inference key from bob.ibm.com, then run docugate tour init.`;
                 }
                 else if (error instanceof BobMissingError) {
                     tourError =
@@ -623,6 +681,8 @@ export async function initFlow(root, options = {}) {
     if (role !== 'backend') {
         rows.push(['Tour', tourResult ? `IBM Bob wrote ${tourResult.added.length} screen${tourResult.added.length === 1 ? '' : 's'}` : 'add steps in the browser']);
         rows.push(['Tour button', hasPill && installResult?.target ? installResult.target : 'not added']);
+        if (installResult?.hook)
+            rows.push(['Starts with', `npm run ${installResult.hook.replace(/^pre/, '')}`]);
     }
     io.print(``);
     io.print(`  ${dimmed('╭')} ${bold('DocuGate setup')}`);
@@ -636,11 +696,17 @@ export async function initFlow(root, options = {}) {
     }
     else if (hasPill) {
         io.print(`  ${green('✓')} ${bold('DocuGate is set up.')}`);
-        io.print(`    Start your project as usual (for example ${gold('npm run dev')}) and open it:`);
+        const run = installResult?.hook ? `npm run ${installResult.hook.replace(/^pre/, '')}` : 'npm run dev';
+        io.print(`    Start your project as usual (${gold(run)}) and open it:`);
         io.print(`    the ${gold('Tour')} button is in the bottom-right corner.`);
     }
     else {
         io.print(`  ${green('✓')} ${bold('DocuGate is set up.')} Run docugate tour install to add the Tour button to your app.`);
     }
+    // The answer to "how often" only means something once the Action exists.
+    if (io.isTTY && final.freshness && final.freshness !== 'off') {
+        io.print(``);
+        io.print(`  ${dimmed('Next:')} ${gold(asCommand('docugate sync init'))} ${dimmed(`adds the GitHub Action that keeps the docs current (${final.freshness})`)}`);
+    }
     return { ...base, role, tourResult, tourError, installResult, connectError };
 }

package/dist/keys/core.d.ts

@@ -0,0 +1,108 @@
+/** What DocuGate says about one key. `valid: false` always comes with the reason. */
+export type KeyVerdict = {
+    valid: true;
+    code: 'VALID';
+    keyId: string;
+    /** The name the holder gave the key. */
+    name: string;
+    scopes: string[];
+    /** Who generated it. Yours to use or ignore: it is their DocuGate account. */
+    user: {
+        id: string;
+        email: string;
+        name: string;
+    };
+    /** `limit` and `remaining` are null for a key with no allowance. */
+    usage: {
+        used: number;
+        limit: number | null;
+        remaining: number | null;
+    };
+    expiresAt: string | null;
+} | {
+    valid: false;
+    code: 'MALFORMED' | 'NOT_FOUND' | 'REVOKED' | 'EXPIRED' | 'USAGE_EXCEEDED' | 'MISSING_SCOPE' | 'KEYS_DISABLED' | 'PLAN_LAPSED';
+};
+export type ValidKey = Extract<KeyVerdict, {
+    valid: true;
+}>;
+export interface VerifyOptions {
+    /** From your space's settings in DocuGate. Starts with `dgs_`. Keep it in an environment variable. */
+    secret: string;
+    /** Only for a self-hosted DocuGate. Defaults to `DOCUGATE_URL`, then the hosted service. */
+    baseUrl?: string;
+    /** How long to wait for DocuGate before giving up. Defaults to 5000. */
+    timeoutMs?: number;
+    /** For tests, or an environment with its own `fetch`. */
+    fetch?: typeof fetch;
+}
+/** DocuGate could not be asked, or refused to answer. Never means a key is bad. */
+export declare class KeyServiceError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Ask DocuGate about one key.
+ *
+ * Resolves with a verdict for every key, valid or not. It rejects, with a
+ * `KeyServiceError`, only when it could not get an answer: DocuGate was
+ * unreachable, or your secret was refused. Those are not the key's fault, so
+ * they are not a verdict.
+ */
+export declare function verifyKey(key: string, options: VerifyOptions & {
+    scope?: string;
+    cost?: number;
+}): Promise<KeyVerdict>;
+export interface RequireKeyOptions extends VerifyOptions {
+    /** A scope the key must hold. Leave out if you do not use scopes. */
+    scope?: string;
+    /** How many calls from the key's allowance this request uses. Defaults to 1. */
+    cost?: number;
+    /**
+     * Where the key is in the request. `authorization` means `Authorization: Bearer <key>`; any
+     * other value is a header name whose whole value is the key. Match what you chose in your
+     * space settings.
+     */
+    header?: string;
+    /**
+     * Seconds to remember a *valid* answer, so a busy API is not asking DocuGate on every request.
+     * The default, 0, asks every time, which is what makes a revoked key stop on its next call.
+     * A request served from this memory does not count against the key's allowance, and a key
+     * revoked in the meantime keeps working until the memory expires.
+     */
+    cacheSeconds?: number;
+    /**
+     * What to do when DocuGate cannot be reached. By default the request is refused with a 503,
+     * because the alternative is accepting keys nobody checked. Set this if your API would rather
+     * stay up than be strict.
+     */
+    failOpen?: boolean;
+}
+/** What an adapter should do with one request. */
+export type Outcome = {
+    kind: 'allow';
+    key: ValidKey | null;
+} | {
+    kind: 'deny';
+    status: number;
+    headers: Record<string, string>;
+    body: {
+        error: string;
+        code?: string;
+    };
+};
+/** The HTTP status a verdict that is not valid should be answered with. */
+export declare function statusFor(code: Extract<KeyVerdict, {
+    valid: false;
+}>['code']): number;
+/** The key in a header's value, or nothing. */
+export declare function readKey(value: string | string[] | undefined, header: string): string | null;
+/**
+ * One function that takes a request's key header and says what to do. The
+ * adapters read the header out of their framework's request and carry out the answer.
+ */
+export declare function createKeyChecker(options: RequireKeyOptions): {
+    header: string;
+    check: (value: string | string[] | undefined) => Promise<Outcome>;
+};

package/dist/keys/core.js

@@ -0,0 +1,142 @@
+import { createHash } from 'node:crypto';
+import { looksLikeKey } from './format.js';
+/**
+ * Checking a DocuGate API key from your own backend.
+ *
+ * A reader of your API docs generates a key on the page. Your backend asks
+ * DocuGate whether a key is valid, with a secret only it holds, and DocuGate
+ * answers from its own records, so a key you revoke stops working on its next
+ * request. This file is that question and what to do with the answer. The
+ * adapters for Express, Hono and Fastify are a few lines on top of it.
+ */
+const DEFAULT_BASE_URL = 'https://www.trydocugate.site';
+/** DocuGate could not be asked, or refused to answer. Never means a key is bad. */
+export class KeyServiceError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'KeyServiceError';
+    }
+}
+/**
+ * Ask DocuGate about one key.
+ *
+ * Resolves with a verdict for every key, valid or not. It rejects, with a
+ * `KeyServiceError`, only when it could not get an answer: DocuGate was
+ * unreachable, or your secret was refused. Those are not the key's fault, so
+ * they are not a verdict.
+ */
+export async function verifyKey(key, options) {
+    const base = (options.baseUrl ?? process.env.DOCUGATE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const send = options.fetch ?? fetch;
+    let res;
+    try {
+        res = await send(`${base}/api/keys/verify`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${options.secret}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ key, scope: options.scope, cost: options.cost }),
+            signal: AbortSignal.timeout(options.timeoutMs ?? 5000),
+        });
+    }
+    catch (cause) {
+        throw new KeyServiceError('DocuGate could not be reached to check an API key.', { cause });
+    }
+    if (res.status === 401) {
+        throw new KeyServiceError('DocuGate refused the verify secret. Check it matches the one in your space settings.');
+    }
+    if (!res.ok)
+        throw new KeyServiceError(`DocuGate answered ${res.status} when checking an API key.`);
+    const body = (await res.json().catch(() => null));
+    if (!body || typeof body.valid !== 'boolean')
+        throw new KeyServiceError('DocuGate sent an answer that could not be read.');
+    return body;
+}
+/** The HTTP status a verdict that is not valid should be answered with. */
+export function statusFor(code) {
+    if (code === 'MISSING_SCOPE')
+        return 403;
+    if (code === 'USAGE_EXCEEDED')
+        return 429;
+    // Not the caller's fault and not fixable by them: the owner's plan or settings.
+    if (code === 'PLAN_LAPSED' || code === 'KEYS_DISABLED')
+        return 503;
+    return 401;
+}
+/** The key in a header's value, or nothing. */
+export function readKey(value, header) {
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (!raw)
+        return null;
+    if (header.toLowerCase() !== 'authorization')
+        return raw.trim() || null;
+    const match = /^Bearer\s+(\S+)$/i.exec(raw.trim());
+    return match ? match[1] : null;
+}
+const unauthorised = (code, error) => ({
+    kind: 'deny',
+    status: 401,
+    headers: { 'WWW-Authenticate': 'Bearer' },
+    body: { error, code },
+});
+/**
+ * One function that takes a request's key header and says what to do. The
+ * adapters read the header out of their framework's request and carry out the answer.
+ */
+export function createKeyChecker(options) {
+    if (typeof options.secret !== 'string' || !options.secret.startsWith('dgs_')) {
+        throw new Error('requireKey needs the verify secret from your space settings in DocuGate. It starts with dgs_ — ' +
+            'pass it from an environment variable.');
+    }
+    const header = (options.header ?? 'authorization').toLowerCase();
+    const cacheMs = Math.max(0, options.cacheSeconds ?? 0) * 1000;
+    const remembered = new Map();
+    async function check(value) {
+        const key = readKey(value, header);
+        if (!key)
+            return unauthorised('MISSING', 'api_key_required');
+        // A string that cannot be a key never costs a network call.
+        if (!looksLikeKey(key))
+            return unauthorised('MALFORMED', 'invalid_api_key');
+        // Remembered by a hash, so the key itself is not kept in memory.
+        const id = cacheMs ? createHash('sha256').update(`${options.scope ?? ''}\n${key}`).digest('hex') : '';
+        const hit = cacheMs ? remembered.get(id) : undefined;
+        if (hit && hit.until > Date.now())
+            return { kind: 'allow', key: hit.key };
+        let verdict;
+        try {
+            verdict = await verifyKey(key, options);
+        }
+        catch (error) {
+            if (options.failOpen)
+                return { kind: 'allow', key: null };
+            return {
+                kind: 'deny',
+                status: 503,
+                headers: {},
+                body: { error: 'key_service_unavailable', code: error instanceof KeyServiceError ? 'UNAVAILABLE' : undefined },
+            };
+        }
+        if (verdict.valid) {
+            if (cacheMs) {
+                // A busy API must not grow this without bound: drop what has expired first.
+                if (remembered.size > 5000) {
+                    const now = Date.now();
+                    for (const [k, v] of remembered)
+                        if (v.until <= now)
+                            remembered.delete(k);
+                    if (remembered.size > 5000)
+                        remembered.clear();
+                }
+                remembered.set(id, { until: Date.now() + cacheMs, key: verdict });
+            }
+            return { kind: 'allow', key: verdict };
+        }
+        const status = statusFor(verdict.code);
+        return {
+            kind: 'deny',
+            status,
+            headers: status === 401 ? { 'WWW-Authenticate': 'Bearer' } : {},
+            body: { error: status === 401 ? 'invalid_api_key' : status === 403 ? 'forbidden' : status === 429 ? 'usage_exceeded' : 'key_service_unavailable', code: verdict.code },
+        };
+    }
+    return { header, check };
+}

package/dist/keys/express.d.ts

@@ -0,0 +1,21 @@
+import type { RequireKeyOptions, ValidKey } from './core.js';
+export type { KeyVerdict, RequireKeyOptions, ValidKey } from './core.js';
+/** The parts of an Express request this uses, so Express itself is not a dependency. */
+interface Req {
+    headers: Record<string, string | string[] | undefined>;
+    /** Set to the verified key. Absent when `failOpen` let a request through unchecked. */
+    docugateKey?: ValidKey | null;
+}
+interface Res {
+    status(code: number): Res;
+    setHeader(name: string, value: string): unknown;
+    json(body: unknown): unknown;
+}
+/**
+ * Express middleware that lets a request through only if it carries a valid
+ * DocuGate API key. The verified key is on `req.docugateKey`.
+ *
+ *     import { requireKey } from 'docugate/express'
+ *     app.use('/api', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))
+ */
+export declare function requireKey(options: RequireKeyOptions): (req: Req, res: Res, next: (error?: unknown) => void) => Promise<void>;

package/dist/keys/express.js

@@ -0,0 +1,27 @@
+import { createKeyChecker } from './core.js';
+/**
+ * Express middleware that lets a request through only if it carries a valid
+ * DocuGate API key. The verified key is on `req.docugateKey`.
+ *
+ *     import { requireKey } from 'docugate/express'
+ *     app.use('/api', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))
+ */
+export function requireKey(options) {
+    const { header, check } = createKeyChecker(options);
+    return async (req, res, next) => {
+        try {
+            const outcome = await check(req.headers[header]);
+            if (outcome.kind === 'deny') {
+                for (const [name, value] of Object.entries(outcome.headers))
+                    res.setHeader(name, value);
+                res.status(outcome.status).json(outcome.body);
+                return;
+            }
+            req.docugateKey = outcome.key;
+            next();
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}

package/dist/keys/fastify.d.ts

@@ -0,0 +1,21 @@
+import type { RequireKeyOptions, ValidKey } from './core.js';
+export type { KeyVerdict, RequireKeyOptions, ValidKey } from './core.js';
+/** The parts of a Fastify request and reply this uses, so Fastify itself is not a dependency. */
+interface Request {
+    headers: Record<string, string | string[] | undefined>;
+    /** Set to the verified key. Null when `failOpen` let a request through unchecked. */
+    docugateKey?: ValidKey | null;
+}
+interface Reply {
+    code(status: number): Reply;
+    header(name: string, value: string): Reply;
+    send(body: unknown): Reply;
+}
+/**
+ * A Fastify hook that lets a request through only if it carries a valid
+ * DocuGate API key. The verified key is `request.docugateKey`.
+ *
+ *     import { requireKey } from 'docugate/fastify'
+ *     app.addHook('preHandler', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))
+ */
+export declare function requireKey(options: RequireKeyOptions): (request: Request, reply: Reply) => Promise<Reply | undefined>;

package/dist/keys/fastify.js

@@ -0,0 +1,21 @@
+import { createKeyChecker } from './core.js';
+/**
+ * A Fastify hook that lets a request through only if it carries a valid
+ * DocuGate API key. The verified key is `request.docugateKey`.
+ *
+ *     import { requireKey } from 'docugate/fastify'
+ *     app.addHook('preHandler', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))
+ */
+export function requireKey(options) {
+    const { header, check } = createKeyChecker(options);
+    return async (request, reply) => {
+        const outcome = await check(request.headers[header]);
+        if (outcome.kind === 'deny') {
+            for (const [name, value] of Object.entries(outcome.headers))
+                reply.header(name, value);
+            // Returning the reply is how an async Fastify hook says "I have answered".
+            return reply.code(outcome.status).send(outcome.body);
+        }
+        request.docugateKey = outcome.key;
+    };
+}

package/dist/keys/format.d.ts

@@ -0,0 +1,11 @@
+/**
+ * What a DocuGate API key looks like, so a request that cannot possibly hold one
+ * is refused without a round trip.
+ *
+ * This is a copy of the server's `isWellFormedKey` (`server/apiKeys.ts`), not an
+ * import of it: this package is published on its own. Both test suites check the
+ * same two golden keys, so if either side's format moves, a test fails here
+ * before any customer's API does.
+ */
+/** Whether a string has a key's shape and a checksum that matches. Not whether the key exists. */
+export declare function looksLikeKey(value: unknown): value is string;

package/dist/keys/format.js

@@ -0,0 +1,46 @@
+/**
+ * What a DocuGate API key looks like, so a request that cannot possibly hold one
+ * is refused without a round trip.
+ *
+ * This is a copy of the server's `isWellFormedKey` (`server/apiKeys.ts`), not an
+ * import of it: this package is published on its own. Both test suites check the
+ * same two golden keys, so if either side's format moves, a test fails here
+ * before any customer's API does.
+ */
+const PREFIX = 'dg_live_';
+const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+const BODY_LENGTH = 43;
+const CHECKSUM_LENGTH = 6;
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let c = i;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[i] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(text) {
+    let crc = 0xffffffff;
+    for (const byte of Buffer.from(text, 'utf8'))
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function base62(n, length) {
+    let out = '';
+    let rest = n;
+    while (rest > 0) {
+        out = ALPHABET[rest % 62] + out;
+        rest = Math.floor(rest / 62);
+    }
+    return out.padStart(length, '0');
+}
+/** Whether a string has a key's shape and a checksum that matches. Not whether the key exists. */
+export function looksLikeKey(value) {
+    if (typeof value !== 'string' || value.length !== PREFIX.length + BODY_LENGTH + CHECKSUM_LENGTH)
+        return false;
+    if (!value.startsWith(PREFIX) || !/^[0-9A-Za-z]+$/.test(value.slice(PREFIX.length)))
+        return false;
+    return value.slice(-CHECKSUM_LENGTH) === base62(crc32(value.slice(0, -CHECKSUM_LENGTH)), CHECKSUM_LENGTH);
+}

package/dist/keys/hono.d.ts

@@ -0,0 +1,19 @@
+import type { RequireKeyOptions } from './core.js';
+export type { KeyVerdict, RequireKeyOptions, ValidKey } from './core.js';
+/** The parts of a Hono context this uses, so Hono itself is not a dependency. */
+interface Context {
+    req: {
+        header(name: string): string | undefined;
+    };
+    header(name: string, value: string): void;
+    json(body: unknown, status?: number): Response;
+    set(key: 'docugateKey', value: unknown): void;
+}
+/**
+ * Hono middleware that lets a request through only if it carries a valid
+ * DocuGate API key. The verified key is `c.get('docugateKey')`.
+ *
+ *     import { requireKey } from 'docugate/hono'
+ *     app.use('/api/*', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))
+ */
+export declare function requireKey(options: RequireKeyOptions): (c: Context, next: () => Promise<void>) => Promise<Response | undefined>;