@invokable/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Invokable
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @invokable/server
+
+Self-hostable device-code auth for [invokable](https://github.com/beinvokable/invokable)
+tools. Implements the five endpoints `@invokable/core`'s `login` command talks to.
+
+## Use
+
+```js
+import { createServer } from 'node:http';
+import { invokableAuth, memoryStore } from '@invokable/server';
+import { nodeListener } from '@invokable/server/node';
+
+const handler = invokableAuth({
+  store: memoryStore(),                    // swap for a durable store
+  tokenPrefix: 'mtl',
+  requireSession: (request) => getUserFromCookie(request),  // your login
+  approvePage: ({ device, user }) => renderMyBrandedPage(device, user),
+  tokenTtl: null,                          // long-lived; revocation only
+});
+
+createServer(nodeListener(handler)).listen(8787);
+```
+
+`invokableAuth` returns a fetch-style `(Request) => Promise<Response | null>`.
+`null` means "not my route", so it composes with your own routing. Hono, Deno and
+workers can call it directly; `./node` adapts it to `node:http` and Express
+(`expressMiddleware`).
+
+A runnable version is in
+[`examples/server`](../../examples/server/server.mjs).
+
+## Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| `POST` | `/device/start` | Issues a device code + user code |
+| `GET` | `/device?code=…` | The approval page a human sees |
+| `POST` | `/device/approve` | Records the decision — **requires a session** |
+| `POST` | `/device/token` | Polled by the CLI until approved |
+| `GET` | `/cli/whoami` | Identity behind the bearer token |
+| `POST` | `/cli/logout` | Revokes the bearer token |
+
+## What it does about security
+
+- **Tokens are stored hashed.** `<prefix>_<32 chars base62>` is returned to the
+  client once; only a SHA-256 digest is persisted. A dump of the store does not
+  yield working credentials.
+- **Device codes are single-use.** Issuing a token marks the device `consumed`,
+  so a leaked device code cannot be replayed into a second credential.
+- **Polling is rate-limited.** Polling faster than the advertised interval gets
+  `slow_down`, not a token.
+- **Approval requires a session.** `requireSession` returning null means nothing
+  can be approved, and the endpoint answers 401.
+- **User codes avoid ambiguous characters** (no `0/O/1/I/L`): they get read aloud
+  and typed by hand.
+
+## What it does *not* do — read before deploying
+
+**Device-code phishing is the attack this flow is exposed to.** An attacker
+starts a login on their own machine, sends you the code, and asks you to approve
+it; the token is then issued to *them*, against *your* identity. Nothing in the
+protocol prevents this — the defence is the user recognising a login they did not
+start.
+
+The default approval page therefore shows the tool, version, and hostname the
+device reported, and says plainly that you should only approve a login you just
+started. **If you supply your own `approvePage`, keep that.** A page that shows
+only a code and an Approve button is materially less safe.
+
+Also not handled here, and yours to add:
+
+- **CSRF on `/device/approve`.** The handler checks a session, not a CSRF token.
+  If you serve the default form-based page from a cookie-authenticated origin,
+  add your framework's CSRF protection.
+- **Rate limiting on `/device/start`.** Nothing stops an attacker minting device
+  codes in bulk.
+- **Durable storage.** `memoryStore()` loses every token on restart. It is for
+  development and tests. A Postgres store is on the roadmap.
+- **Audit logging.** The store records who approved what and when; surfacing it
+  is the host application's job.

package/dist/checkpoint-routes.d.ts

@@ -0,0 +1,40 @@
+import { CheckpointVerifier, type CheckpointFailure } from './checkpoints.js';
+export interface CheckpointRoutesOptions {
+    verifier: CheckpointVerifier;
+    /**
+     * Identifies the caller from the request, so a fingerprint issued to one
+     * subject cannot be verified by another. Returning null still allows
+     * issuance; supply it in production.
+     */
+    identify?: (request: Request) => string | null | Promise<string | null>;
+}
+/** Maps a verification failure onto the 409 the client turns into exit 12. */
+export declare function staleResponse(reason: CheckpointFailure, retryCommand?: string, detail?: string): Response;
+/**
+ * `POST /checkpoints` (issue) and `POST /checkpoints/verify` (non-consuming
+ * check). Returns null for paths it does not own.
+ *
+ * Verification here is deliberately NOT consuming: the approval is burned by
+ * `verifyCheckpoint` on the action request itself, so the approval is spent by
+ * the operation it authorised rather than by a preflight call.
+ */
+export declare function checkpointRoutes(options: CheckpointRoutesOptions): (request: Request) => Promise<Response | null>;
+export interface VerifyCheckpointOptions {
+    verifier: CheckpointVerifier;
+    /**
+     * Which requests require an approval. Defaults to every non-GET request,
+     * which is safe-by-default but usually too broad — narrow it to the routes
+     * that actually spend.
+     */
+    requiresApproval?: (request: Request) => boolean;
+    /** Recomputes the subject for the incoming request, to bind gate to target. */
+    subjectFor?: (request: Request) => string | Promise<string>;
+}
+/**
+ * Middleware that performs steps 1-4 of spec 5.8 on the action request, burning
+ * the approval as the action is authorised.
+ *
+ * Returns a 409 Response to reject, or null to let the request proceed.
+ */
+export declare function verifyCheckpoint(options: VerifyCheckpointOptions): (request: Request) => Promise<Response | null>;
+//# sourceMappingURL=checkpoint-routes.d.ts.map

package/dist/checkpoint-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-routes.d.ts","sourceRoot":"","sources":["../src/checkpoint-routes.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAGlB,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACzE;AAkBD,8EAA8E;AAC9E,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,EACzB,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,QAAQ,CAaV;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,IAGlC,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA+CzE;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;IACjD,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,IAOnC,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA0BxE"}

package/dist/checkpoint-routes.js

@@ -0,0 +1,112 @@
+import { stableStringify } from './stable-json.js';
+import { CheckpointVerifier, hashSummary, parseCheckpointHeader, } from './checkpoints.js';
+function json(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+const STALE_MESSAGE = {
+    not_found: 'No approval matches that fingerprint.',
+    gate_mismatch: 'That approval was issued for a different gate.',
+    subject_mismatch: 'That approval was issued for a different target.',
+    mismatch: 'The plan changed since this approval was issued.',
+    expired: 'This approval has expired.',
+    consumed: 'This approval was already used.',
+};
+/** Maps a verification failure onto the 409 the client turns into exit 12. */
+export function staleResponse(reason, retryCommand, detail) {
+    return json({
+        error: 'checkpoint_stale',
+        code: 'checkpoint_stale',
+        // The detail names a wiring mistake precisely; without it a subject
+        // mismatch is indistinguishable from a forged fingerprint.
+        message: detail ? `${STALE_MESSAGE[reason]} (${detail})` : STALE_MESSAGE[reason],
+        reason,
+        remediation: retryCommand ?? 'Re-run the command without --approve to get a fresh plan.',
+    }, 409);
+}
+/**
+ * `POST /checkpoints` (issue) and `POST /checkpoints/verify` (non-consuming
+ * check). Returns null for paths it does not own.
+ *
+ * Verification here is deliberately NOT consuming: the approval is burned by
+ * `verifyCheckpoint` on the action request itself, so the approval is spent by
+ * the operation it authorised rather than by a preflight call.
+ */
+export function checkpointRoutes(options) {
+    const { verifier, identify } = options;
+    return async function handle(request) {
+        const url = new URL(request.url);
+        const path = url.pathname.replace(/\/+$/, '') || '/';
+        const method = request.method.toUpperCase();
+        if (path.endsWith('/checkpoints') && method === 'POST') {
+            const body = (await request.json().catch(() => ({})));
+            const gate = String(body['gate'] ?? '');
+            if (!gate)
+                return json({ error: 'usage', message: '`gate` is required.' }, 400);
+            const subject = String(body['subject'] ?? '');
+            const issuedTo = (await identify?.(request)) ?? undefined;
+            const record = await verifier.issue({
+                gate,
+                subject,
+                summaryHash: hashSummary(stableStringify(body['summary'] ?? null)),
+                ...(issuedTo !== undefined ? { issuedTo } : {}),
+            });
+            return json({
+                fingerprint: record.fingerprint,
+                gate: record.gate,
+                expiresAt: new Date(record.expiresAt).toISOString(),
+            });
+        }
+        if (path.endsWith('/checkpoints/verify') && method === 'POST') {
+            const body = (await request.json().catch(() => ({})));
+            const gate = String(body['gate'] ?? '');
+            const subject = String(body['subject'] ?? '');
+            const fingerprint = String(body['fingerprint'] ?? '');
+            const expected = body['summaryHash'];
+            const result = await verifier.verify({
+                gate,
+                subject,
+                fingerprint,
+                ...(typeof expected === 'string' ? { expectedSummaryHash: expected } : {}),
+            });
+            if (!result.ok)
+                return staleResponse(result.reason ?? 'not_found', undefined, result.detail);
+            return json({ valid: true, gate, expiresAt: new Date(result.record.expiresAt).toISOString() });
+        }
+        return null;
+    };
+}
+/**
+ * Middleware that performs steps 1-4 of spec 5.8 on the action request, burning
+ * the approval as the action is authorised.
+ *
+ * Returns a 409 Response to reject, or null to let the request proceed.
+ */
+export function verifyCheckpoint(options) {
+    const { verifier, requiresApproval = (req) => req.method.toUpperCase() !== 'GET', subjectFor, } = options;
+    return async function check(request) {
+        if (!requiresApproval(request))
+            return null;
+        const header = parseCheckpointHeader(request.headers.get('x-invokable-checkpoint'));
+        if (!header) {
+            return json({
+                error: 'checkpoint_required',
+                code: 'checkpoint_stale',
+                message: 'This action requires an approval fingerprint.',
+                remediation: 'Re-run the command without --approve to get a fresh plan.',
+            }, 409);
+        }
+        const subject = subjectFor ? await subjectFor(request) : '';
+        const result = await verifier.consume({
+            gate: header.gate,
+            subject,
+            fingerprint: header.fingerprint,
+        });
+        if (!result.ok)
+            return staleResponse(result.reason ?? 'not_found', undefined, result.detail);
+        return null;
+    };
+}
+//# sourceMappingURL=checkpoint-routes.js.map

package/dist/checkpoint-routes.js.map

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

package/dist/checkpoints.d.ts

@@ -0,0 +1,93 @@
+export interface FingerprintInput {
+    gate: string;
+    subject: string;
+    summaryHash: string;
+    issuedAt: number;
+}
+/**
+ * 16 base32 characters = 80 bits. Sufficient because a fingerprint is scoped to
+ * (gate, subject), is consumed once, and expires — it is not a bearer secret.
+ */
+export declare function computeFingerprint(secret: string, input: FingerprintInput): string;
+export declare function hashSummary(canonical: string): string;
+export interface CheckpointRecord {
+    fingerprint: string;
+    gate: string;
+    subject: string;
+    summaryHash: string;
+    issuedAt: number;
+    expiresAt: number;
+    consumed: boolean;
+    consumedAt?: number;
+    /** Whoever the token belonged to when the checkpoint was issued. */
+    issuedTo?: string;
+}
+export interface CheckpointStore {
+    createCheckpoint(record: CheckpointRecord): Promise<void>;
+    /**
+     * Looks up by fingerprint alone. The gate and subject are compared by the
+     * verifier rather than folded into the query, so that an approval issued for
+     * a different target can be reported as such instead of as "unknown".
+     */
+    findCheckpoint(fingerprint: string): Promise<CheckpointRecord | null>;
+    consumeCheckpoint(fingerprint: string, at: number): Promise<boolean>;
+}
+export declare function memoryCheckpointStore(): CheckpointStore & {
+    _records: Map<string, CheckpointRecord>;
+};
+export type CheckpointFailure = 'not_found' | 'gate_mismatch' | 'subject_mismatch' | 'mismatch' | 'expired' | 'consumed';
+export interface VerifyResult {
+    ok: boolean;
+    reason?: CheckpointFailure;
+    record?: CheckpointRecord;
+    /** Extra context for a mismatch, safe to show a developer. */
+    detail?: string;
+}
+export interface CheckpointVerifierOptions {
+    secret: string;
+    /** Honoured for 24h after rotation, so in-flight approvals keep working. */
+    previousSecret?: string;
+    store: CheckpointStore;
+    /** Default 24 hours (spec 5.8). */
+    ttlMs?: number;
+    now?: () => number;
+}
+export declare class CheckpointVerifier {
+    private readonly secret;
+    private readonly previousSecret;
+    private readonly store;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(options: CheckpointVerifierOptions);
+    issue(input: {
+        gate: string;
+        subject: string;
+        summaryHash: string;
+        issuedTo?: string;
+    }): Promise<CheckpointRecord>;
+    /**
+     * Steps 1-3 of spec 5.8: the record exists, the MAC still recomputes from
+     * stored state, and it is neither expired nor already consumed.
+     *
+     * `expectedSummaryHash` is the caller's view of current state. Supplying it
+     * is what makes an approval *stale* when the plan changed underneath.
+     */
+    verify(input: {
+        gate: string;
+        subject: string;
+        fingerprint: string;
+        expectedSummaryHash?: string;
+    }): Promise<VerifyResult>;
+    /** Step 4: verify, then burn. Returns false if it could not be consumed. */
+    consume(input: {
+        gate: string;
+        subject: string;
+        fingerprint: string;
+        expectedSummaryHash?: string;
+    }): Promise<VerifyResult>;
+}
+export declare function parseCheckpointHeader(value: string | null): {
+    gate: string;
+    fingerprint: string;
+} | null;
+//# sourceMappingURL=checkpoints.d.ts.map

package/dist/checkpoints.d.ts.map

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

package/dist/checkpoints.js

@@ -0,0 +1,179 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * Server-issued checkpoint fingerprints (spec 5.8).
+ *
+ * The fingerprint is an HMAC, not a hash of the summary, so it cannot be
+ * computed by anyone who merely saw the summary — including the agent. What it
+ * buys is freshness (an approval cannot outlive the state it described) and
+ * single use (an approval cannot be replayed). It does not contain a hostile
+ * agent: see the security note in the package README.
+ */
+const BASE32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+function base32(buffer) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of buffer) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += BASE32[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0)
+        out += BASE32[(value << (5 - bits)) & 31];
+    return out;
+}
+/**
+ * 16 base32 characters = 80 bits. Sufficient because a fingerprint is scoped to
+ * (gate, subject), is consumed once, and expires — it is not a bearer secret.
+ */
+export function computeFingerprint(secret, input) {
+    const mac = createHmac('sha256', secret)
+        .update(`${input.gate}|${input.subject}|${input.summaryHash}|${input.issuedAt}`, 'utf8')
+        .digest();
+    return base32(mac).slice(0, 16);
+}
+export function hashSummary(canonical) {
+    return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+function constantTimeEqual(a, b) {
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+export function memoryCheckpointStore() {
+    const records = new Map();
+    return {
+        _records: records,
+        async createCheckpoint(record) {
+            records.set(record.fingerprint, record);
+        },
+        async findCheckpoint(fingerprint) {
+            return records.get(fingerprint) ?? null;
+        },
+        async consumeCheckpoint(fingerprint, at) {
+            const found = records.get(fingerprint);
+            // Consumption must be atomic: two concurrent requests carrying the same
+            // fingerprint must not both succeed. A real store does this with a
+            // conditional update; the Map is single-threaded, so the check suffices.
+            if (!found || found.consumed)
+                return false;
+            records.set(fingerprint, { ...found, consumed: true, consumedAt: at });
+            return true;
+        },
+    };
+}
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+export class CheckpointVerifier {
+    secret;
+    previousSecret;
+    store;
+    ttlMs;
+    now;
+    constructor(options) {
+        if (!options.secret) {
+            throw new TypeError('CheckpointVerifier requires a secret.');
+        }
+        this.secret = options.secret;
+        this.previousSecret = options.previousSecret;
+        this.store = options.store;
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.now = options.now ?? (() => Date.now());
+    }
+    async issue(input) {
+        const issuedAt = this.now();
+        const fingerprint = computeFingerprint(this.secret, {
+            gate: input.gate,
+            subject: input.subject,
+            summaryHash: input.summaryHash,
+            issuedAt,
+        });
+        const record = {
+            fingerprint,
+            gate: input.gate,
+            subject: input.subject,
+            summaryHash: input.summaryHash,
+            issuedAt,
+            expiresAt: issuedAt + this.ttlMs,
+            consumed: false,
+            ...(input.issuedTo !== undefined ? { issuedTo: input.issuedTo } : {}),
+        };
+        await this.store.createCheckpoint(record);
+        return record;
+    }
+    /**
+     * Steps 1-3 of spec 5.8: the record exists, the MAC still recomputes from
+     * stored state, and it is neither expired nor already consumed.
+     *
+     * `expectedSummaryHash` is the caller's view of current state. Supplying it
+     * is what makes an approval *stale* when the plan changed underneath.
+     */
+    async verify(input) {
+        const record = await this.store.findCheckpoint(input.fingerprint);
+        if (!record)
+            return { ok: false, reason: 'not_found' };
+        // Reported separately from "not found". A gate or subject that disagrees
+        // between the CLI and the middleware is a wiring mistake, and calling it an
+        // unknown fingerprint sends the integrator looking in the wrong place.
+        if (record.gate !== input.gate) {
+            return {
+                ok: false,
+                reason: 'gate_mismatch',
+                record,
+                detail: `issued for gate "${record.gate}", presented for "${input.gate}"`,
+            };
+        }
+        if (record.subject !== input.subject) {
+            return {
+                ok: false,
+                reason: 'subject_mismatch',
+                record,
+                detail: `issued for subject ${JSON.stringify(record.subject)}, presented for ` +
+                    `${JSON.stringify(input.subject)} — the \`subject\` passed to checkpoint() must ` +
+                    'equal what `subjectFor` returns in verifyCheckpoint()',
+            };
+        }
+        const recomputes = [this.secret, this.previousSecret]
+            .filter((s) => Boolean(s))
+            .some((secret) => constantTimeEqual(computeFingerprint(secret, {
+            gate: record.gate,
+            subject: record.subject,
+            summaryHash: record.summaryHash,
+            issuedAt: record.issuedAt,
+        }), input.fingerprint));
+        if (!recomputes)
+            return { ok: false, reason: 'mismatch', record };
+        if (input.expectedSummaryHash !== undefined &&
+            !constantTimeEqual(record.summaryHash, input.expectedSummaryHash)) {
+            return { ok: false, reason: 'mismatch', record };
+        }
+        if (record.expiresAt <= this.now())
+            return { ok: false, reason: 'expired', record };
+        if (record.consumed)
+            return { ok: false, reason: 'consumed', record };
+        return { ok: true, record };
+    }
+    /** Step 4: verify, then burn. Returns false if it could not be consumed. */
+    async consume(input) {
+        const result = await this.verify(input);
+        if (!result.ok)
+            return result;
+        const consumed = await this.store.consumeCheckpoint(input.fingerprint, this.now());
+        if (!consumed)
+            return { ok: false, reason: 'consumed', ...(result.record ? { record: result.record } : {}) };
+        return result;
+    }
+}
+export function parseCheckpointHeader(value) {
+    if (!value)
+        return null;
+    const at = value.lastIndexOf('@');
+    if (at <= 0 || at === value.length - 1)
+        return null;
+    return { gate: value.slice(0, at), fingerprint: value.slice(at + 1) };
+}
+//# sourceMappingURL=checkpoints.js.map

package/dist/checkpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoints.js","sourceRoot":"","sources":["../src/checkpoints.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE;;;;;;;;GAQG;AAEH,MAAM,MAAM,GAAG,kCAAkC,CAAC;AAElD,SAAS,MAAM,CAAC,MAAc;IAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QAC5B,IAAI,IAAI,CAAC,CAAC;QACV,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC;YACjB,GAAG,IAAI,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;YAC3C,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;IACH,CAAC;IACD,IAAI,IAAI,GAAG,CAAC;QAAE,GAAG,IAAI,MAAM,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IACxD,OAAO,GAAG,CAAC;AACb,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,KAAuB;IACxE,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SACrC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC;SACvF,MAAM,EAAE,CAAC;IACZ,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,iBAAiB,CAAC,CAAS,EAAE,CAAS;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC9C,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AA0BD,MAAM,UAAU,qBAAqB;IAGnC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;IACpD,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,KAAK,CAAC,gBAAgB,CAAC,MAAM;YAC3B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC1C,CAAC;QACD,KAAK,CAAC,cAAc,CAAC,WAAW;YAC9B,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;QAC1C,CAAC;QACD,KAAK,CAAC,iBAAiB,CAAC,WAAW,EAAE,EAAE;YACrC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACvC,wEAAwE;YACxE,mEAAmE;YACnE,yEAAyE;YACzE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ;gBAAE,OAAO,KAAK,CAAC;YAC3C,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC;AA4BD,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE3C,MAAM,OAAO,kBAAkB;IACZ,MAAM,CAAS;IACf,cAAc,CAAqB;IACnC,KAAK,CAAkB;IACvB,KAAK,CAAS;IACd,GAAG,CAAe;IAEnC,YAAY,OAAkC;QAC5C,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACpB,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC;QAC7C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,KAKX;QACC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5B,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE;YAClD,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,QAAQ;SACT,CAAC,CAAC;QAEH,MAAM,MAAM,GAAqB;YAC/B,WAAW;YACX,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,QAAQ;YACR,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC,KAAK;YAChC,QAAQ,EAAE,KAAK;YACf,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtE,CAAC;QACF,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC1C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,KAKZ;QACC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAClE,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAEvD,yEAAyE;QACzE,4EAA4E;QAC5E,uEAAuE;QACvE,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;YAC/B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,eAAe;gBACvB,MAAM;gBACN,MAAM,EAAE,oBAAoB,MAAM,CAAC,IAAI,qBAAqB,KAAK,CAAC,IAAI,GAAG;aAC1E,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;YACrC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,kBAAkB;gBAC1B,MAAM;gBACN,MAAM,EACJ,sBAAsB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,kBAAkB;oBACtE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,iDAAiD;oBACjF,uDAAuD;aAC1D,CAAC;QACJ,CAAC;QAED,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,CAAC;aAClD,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;aACtC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CACf,iBAAiB,CACf,kBAAkB,CAAC,MAAM,EAAE;YACzB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B,CAAC,EACF,KAAK,CAAC,WAAW,CAClB,CACF,CAAC;QACJ,IAAI,CAAC,UAAU;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAElE,IACE,KAAK,CAAC,mBAAmB,KAAK,SAAS;YACvC,CAAC,iBAAiB,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,mBAAmB,CAAC,EACjE,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QACnD,CAAC;QAED,IAAI,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QACpF,IAAI,MAAM,CAAC,QAAQ;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAEtE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,OAAO,CAAC,KAKb;QACC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,MAAM,CAAC;QAC9B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAC7G,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,MAAM,UAAU,qBAAqB,CACnC,KAAoB;IAEpB,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,EAAE,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;AACxE,CAAC"}

package/dist/handler.d.ts

@@ -0,0 +1,48 @@
+import type { AuthStore, DeviceRecord } from './store.js';
+export interface SessionUser {
+    subject: string;
+    orgId?: string;
+    displayName?: string;
+}
+export interface ApprovePageContext {
+    userCode: string;
+    /** Null when no device is pending for that code. */
+    device: DeviceRecord | null;
+    user: SessionUser | null;
+}
+export interface InvokableAuthOptions {
+    store: AuthStore;
+    /**
+     * Resolves the browser session on the approval page. Return null for a signed
+     * -out visitor; the handler will not approve anything without a user.
+     */
+    requireSession: (request: Request) => SessionUser | null | Promise<SessionUser | null>;
+    /** Renders the branded approval page. A plain default is used when omitted. */
+    approvePage?: (ctx: ApprovePageContext) => string | Promise<string>;
+    /** Token prefix, e.g. `mtl`. Appears in the credential and in `doctor`. */
+    tokenPrefix?: string;
+    /** Milliseconds; `null` means long-lived with revocation only. */
+    tokenTtl?: number | null;
+    /** How long a device code stays valid. Default 15 minutes. */
+    deviceCodeTtlMs?: number;
+    /** Minimum seconds between polls before answering `slow_down`. Default 5. */
+    pollIntervalSeconds?: number;
+    /** Injectable clock, for tests. */
+    now?: () => number;
+}
+/**
+ * The five device-flow endpoints of spec 5.4, as a fetch-style handler:
+ *
+ *   POST /device/start    → device + user code
+ *   GET  /device?code=…   → approval page
+ *   POST /device/approve  → records the user's decision (session required)
+ *   POST /device/token    → polled by the CLI until approved
+ *   POST /cli/logout      → revokes the bearer token
+ *   GET  /cli/whoami      → identity behind the bearer token
+ *
+ * Returns null for paths it does not own, so a host application can mount it
+ * alongside its own routes.
+ */
+export declare function invokableAuth(options: InvokableAuthOptions): (request: Request) => Promise<Response | null>;
+export type InvokableAuthHandler = ReturnType<typeof invokableAuth>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AAEvE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvF,+EAA+E;IAC/E,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AA6DD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,IAsB5B,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAoJzE;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC"}