@cogenta/auth 0.3.0 → 0.5.1

package/dist/api-keys.d.ts

@@ -1,19 +1,108 @@
 import { type DatabaseHandle } from '@cogenta/core';
-import type { ApiKey, CreateApiKeyInput, IssuedApiKey } from './types.js';
+import type { ApiKey, ApiKeyRotationResult, ApiKeyUsage, CreateApiKeyInput, IssuedApiKey } from './types.js';
+/**
+ * A generous but real per-key request quota (fiche 20, "décisions à
+ * prendre"): high enough that no legitimate integration ever notices it,
+ * low enough that a leaked key cannot read the whole site as fast as the
+ * network allows. Applied whenever a key is minted — by `create` or by
+ * `rotate` — without an explicit quota of its own.
+ */
+export declare const DEFAULT_RATE_LIMIT_PER_MINUTE = 600;
+/**
+ * Fiche 62 task 2: how long a revoked key has to sit before it can be
+ * purged — the same reasoning and the same default as content's own
+ * `DEFAULT_TRASH_RETAIN_DAYS` (`@cogenta/schema`), applied here because a
+ * revoked key is not stored anywhere else: purging too early is the one
+ * mistake `purge()` must never make, since it is a real `DELETE`, not a
+ * second layer of soft state on top of `revoked_at`.
+ */
+export declare const MIN_PURGE_AFTER_REVOKED_DAYS = 30;
+/**
+ * Fiche 62 task 3 (decision "(b)", recommended by the fiche): a key revoked
+ * by mistake is not reactivated — `revoked_at` never goes back to `null` —
+ * but a short window after the mistake, `recover()` mints a replacement the
+ * same way `rotate()` does for an active key. Past this window the only way
+ * back is minting a brand new key from scratch, on purpose: the longer a key
+ * has been dead, the less likely "revoked by mistake" is the true story.
+ */
+export declare const RECOVERY_WINDOW_MS: number;
 /** A raw bearer token is an API key only if it has this shape — checked before any DB lookup. */
 export declare function looksLikeApiKey(token: string): boolean;
+export interface RotateApiKeyOptions {
+    /** How long the replaced key keeps working alongside the new one. */
+    readonly graceMs: number;
+}
+/**
+ * Fiche 67 task 5. Both omitted (the historical call shape, `mcp.tsx`'s
+ * picker among others) still returns every key, unpaginated, byte for byte —
+ * this is additive, not a breaking change to an existing publishable
+ * interface.
+ */
+export interface ListApiKeysOptions {
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/**
+ * Fiche feedback: a key's name/scope/quota had no edit path at all after
+ * creation — only `rotate()` existed, and it reissues the secret under the
+ * *same* name/scope, never a changed one. Every field absent from the patch
+ * is left exactly as saved; `rateLimitPerMinute: null` clears an explicit
+ * quota back to `DEFAULT_RATE_LIMIT_PER_MINUTE`, matching how omitting it at
+ * `create()` time already behaves.
+ */
+export interface UpdateApiKeyInput {
+    readonly name?: string;
+    readonly scope?: readonly string[];
+    readonly rateLimitPerMinute?: number | null;
+}
 export interface ApiKeyStore {
     /** Mints a key and returns the raw secret once. It is never stored or returned again. */
     create(input: CreateApiKeyInput): Promise<IssuedApiKey>;
-    /** Never the raw key or its hash — a prefix is all a list ever shows. */
-    list(): Promise<readonly ApiKey[]>;
+    /** Tri-state patch — see `UpdateApiKeyInput`. Never touches the key's secret, prefix, or lifecycle fields. */
+    update(id: string, patch: UpdateApiKeyInput): Promise<ApiKey>;
+    /** Never the raw key or its hash — a prefix is all a list ever shows. Newest first; `limit`/`offset` page it (fiche 67 task 5), both absent means "every key". */
+    list(options?: ListApiKeysOptions): Promise<readonly ApiKey[]>;
+    getById(id: string): Promise<ApiKey | null>;
     revoke(id: string): Promise<void>;
+    /**
+     * Fiche 62 task 2: a real, permanent `DELETE` — the row and its usage
+     * history are gone, never just hidden. Refuses anything but a key that is
+     * both revoked and has been for at least `MIN_PURGE_AFTER_REVOKED_DAYS`:
+     * an active key (even one technically past its `expiresAt`) is never
+     * purgeable, and neither is a key revoked too recently — see the piège
+     * connu in fiche 62 §5.
+     */
+    purge(id: string): Promise<void>;
+    /**
+     * Fiche 62 task 3, decision (b): recovers from a key revoked by mistake
+     * *without* lifting `revoked_at` — the revoked row stays revoked forever,
+     * exactly as `statusOf` in the admin already assumes. Instead, within
+     * `RECOVERY_WINDOW_MS` of the revocation, this mints a fresh replacement
+     * carrying the same name, scope and quota, the same way `rotate` does for
+     * a live key. Refuses a key that was never revoked (nothing to recover
+     * from — rotate it instead) and a key revoked longer ago than the window.
+     */
+    recover(id: string): Promise<IssuedApiKey>;
     /**
      * Resolves a raw bearer token to the key it names, or `null` if it does not
      * exist, is revoked, or has expired. Touches `lastUsedAt` on success, the
-     * same sliding-window courtesy a session gets.
+     * same sliding-window courtesy a session gets, and counts the call toward
+     * this key's aggregated daily usage (fiche 20 task 4).
      */
     verify(rawKey: string): Promise<ApiKey | null>;
+    /**
+     * "Faire tourner cette clé" (fiche 20 task 2): mints a replacement carrying
+     * the same name, scope and quota, and leaves the original valid for
+     * `graceMs` longer rather than revoking it outright — a rotation with no
+     * window where nothing authenticates.
+     *
+     * Refuses a key that is already revoked or expired: there is nothing left
+     * to hand a grace period to, and calling that "rotation" would hide that
+     * the integration already stopped working.
+     */
+    rotate(id: string, options: RotateApiKeyOptions): Promise<ApiKeyRotationResult>;
+    /** Aggregated call counts over the last 7 and 30 days — never a line per call. */
+    usage(id: string): Promise<ApiKeyUsage>;
 }
 export declare function createApiKeyStore(db: DatabaseHandle, now?: () => number): ApiKeyStore;
 //# sourceMappingURL=api-keys.d.ts.map

package/dist/api-keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../src/api-keys.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,cAAc,EAA0B,MAAM,eAAe,CAAA;AAEzF,OAAO,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAkCzE,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAsCD,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IACvD,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;IAClC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAC/C;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,GAAE,MAAM,MAAiB,GAAG,WAAW,CA8D/F"}
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../src/api-keys.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,cAAc,EAKpB,MAAM,eAAe,CAAA;AAEtB,OAAO,KAAK,EACV,MAAM,EACN,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,YAAY,EACb,MAAM,YAAY,CAAA;AA0BnB;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAA;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAA;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAsB,CAAA;AAWrD,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAuDD,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5C;AAED,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IACvD,8GAA8G;IAC9G,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC7D,kKAAkK;IAClK,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;IAC9D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC3C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAC1C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC9C;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAC/E,kFAAkF;IAClF,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACxC;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,GAAE,MAAM,MAAiB,GAAG,WAAW,CA6S/F"}

package/dist/api-keys.js

@@ -1,8 +1,9 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { CogentaError, identifier, newId, sql } from '@cogenta/core';
+import { CogentaError, identifier, newId, sql, limit as sqlLimit, } from '@cogenta/core';
 import { TABLES } from './tables.js';
 /**
- * Machine-to-machine bearer credentials (L13 task 8).
+ * Machine-to-machine bearer credentials (L13 task 8; lifecycle, quota and
+ * usage added by fiche 20).
  *
  * `resolveActor` in `@cogenta/api` already recognises one bearer-token shape:
  * a session, minted at sign-in for a human. This store mints the other
@@ -22,6 +23,32 @@ const KEY_BYTES = 32;
 const KEY_PREFIX = 'cogenta_sk_';
 /** How much of the raw key stays visible forever, so a list of keys is recognisable. */
 const VISIBLE_PREFIX_LENGTH = 12;
+/**
+ * A generous but real per-key request quota (fiche 20, "décisions à
+ * prendre"): high enough that no legitimate integration ever notices it,
+ * low enough that a leaked key cannot read the whole site as fast as the
+ * network allows. Applied whenever a key is minted — by `create` or by
+ * `rotate` — without an explicit quota of its own.
+ */
+export const DEFAULT_RATE_LIMIT_PER_MINUTE = 600;
+/**
+ * Fiche 62 task 2: how long a revoked key has to sit before it can be
+ * purged — the same reasoning and the same default as content's own
+ * `DEFAULT_TRASH_RETAIN_DAYS` (`@cogenta/schema`), applied here because a
+ * revoked key is not stored anywhere else: purging too early is the one
+ * mistake `purge()` must never make, since it is a real `DELETE`, not a
+ * second layer of soft state on top of `revoked_at`.
+ */
+export const MIN_PURGE_AFTER_REVOKED_DAYS = 30;
+/**
+ * Fiche 62 task 3 (decision "(b)", recommended by the fiche): a key revoked
+ * by mistake is not reactivated — `revoked_at` never goes back to `null` —
+ * but a short window after the mistake, `recover()` mints a replacement the
+ * same way `rotate()` does for an active key. Past this window the only way
+ * back is minting a brand new key from scratch, on purpose: the longer a key
+ * has been dead, the less likely "revoked by mistake" is the true story.
+ */
+export const RECOVERY_WINDOW_MS = 24 * 60 * 60 * 1000;
 function issueKey() {
     return `${KEY_PREFIX}${randomBytes(KEY_BYTES).toString('base64url')}`;
 }
@@ -33,6 +60,10 @@ function hashKey(key) {
 export function looksLikeApiKey(token) {
     return token.startsWith(KEY_PREFIX) && token.length > KEY_PREFIX.length;
 }
+/** `YYYY-MM-DD`, UTC — the same day boundary everywhere, regardless of server timezone. */
+function dayKey(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
 function fromRow(row) {
     return {
         id: row.id,
@@ -44,6 +75,8 @@ function fromRow(row) {
         expiresAt: row.expires_at ?? undefined,
         revokedAt: row.revoked_at ?? undefined,
         lastUsedAt: row.last_used_at ?? undefined,
+        rateLimitPerMinute: row.rate_limit_per_minute ?? DEFAULT_RATE_LIMIT_PER_MINUTE,
+        supersededBy: row.superseded_by ?? undefined,
     };
 }
 function assertScope(scope) {
@@ -55,42 +88,172 @@ function assertScope(scope) {
         });
     }
 }
+function keyNotFound() {
+    return new CogentaError({
+        code: 'API_KEY_NOT_FOUND',
+        message: 'No API key with that id.',
+        hint: 'It may already have been revoked and removed from the list, or the id may be mistyped.',
+    });
+}
 export function createApiKeyStore(db, now = Date.now) {
     const table = identifier(TABLES.apiKeys, db.dialect);
-    return {
-        create: async (input) => {
-            assertScope(input.scope);
-            const key = issueKey();
-            const id = newId(now);
-            const created = new Date(now()).toISOString();
-            const prefix = key.slice(0, VISIBLE_PREFIX_LENGTH);
-            await db.query(sql `
+    const usageTable = identifier(TABLES.apiKeyUsage, db.dialect);
+    async function create(input) {
+        assertScope(input.scope);
+        const key = issueKey();
+        const id = newId(now);
+        const created = new Date(now()).toISOString();
+        const prefix = key.slice(0, VISIBLE_PREFIX_LENGTH);
+        const rateLimitPerMinute = input.rateLimitPerMinute ?? DEFAULT_RATE_LIMIT_PER_MINUTE;
+        await db.query(sql `
         insert into ${table}
-          (id, name, key_hash, key_prefix, scope, created_by, created_at, expires_at, revoked_at, last_used_at)
+          (id, name, key_hash, key_prefix, scope, created_by, created_at, expires_at, revoked_at,
+           last_used_at, rate_limit_per_minute, superseded_by)
         values
           (${id}, ${input.name}, ${hashKey(key)}, ${prefix}, ${JSON.stringify(input.scope)},
-           ${input.createdBy}, ${created}, ${input.expiresAt ?? null}, ${null}, ${null})`);
-            return {
-                id,
-                name: input.name,
-                prefix,
-                scope: input.scope,
-                createdBy: input.createdBy,
-                createdAt: created,
-                expiresAt: input.expiresAt,
-                revokedAt: undefined,
-                lastUsedAt: undefined,
-                key,
-            };
-        },
-        list: async () => {
-            const result = await db.query(sql `select * from ${table} order by created_at desc`);
+           ${input.createdBy}, ${created}, ${input.expiresAt ?? null}, ${null},
+           ${null}, ${rateLimitPerMinute}, ${null})`);
+        return {
+            id,
+            name: input.name,
+            prefix,
+            scope: input.scope,
+            createdBy: input.createdBy,
+            createdAt: created,
+            expiresAt: input.expiresAt,
+            revokedAt: undefined,
+            lastUsedAt: undefined,
+            rateLimitPerMinute,
+            supersededBy: undefined,
+            key,
+        };
+    }
+    async function recordUsage(id) {
+        const day = dayKey(now());
+        const updated = await db.query(sql `update ${usageTable} set count = count + 1 where key_id = ${id} and day = ${day}`);
+        if (updated.rowsAffected > 0)
+            return;
+        // First call of the day for this key: insert the row. A concurrent first
+        // call could lose this race — the unique index on (key_id, day) then
+        // refuses the second insert, and the fallback update picks up the count
+        // that insert would have started at 1.
+        await db
+            .query(sql `insert into ${usageTable} (id, key_id, day, count) values (${newId(now)}, ${id}, ${day}, ${1})`)
+            .catch(() => db.query(sql `update ${usageTable} set count = count + 1 where key_id = ${id} and day = ${day}`));
+    }
+    return {
+        create,
+        list: async (options) => {
+            let statement = sql `select * from ${table} order by created_at desc, id desc`;
+            if (options?.limit !== undefined) {
+                statement = sql `${statement} limit ${sqlLimit(options.limit)} offset ${sqlLimit(options.offset ?? 0)}`;
+            }
+            const result = await db.query(statement);
             return result.rows.map(fromRow);
         },
+        getById: async (id) => {
+            const result = await db.query(sql `select * from ${table} where id = ${id}`);
+            const row = result.rows[0];
+            return row === undefined ? null : fromRow(row);
+        },
+        update: async (id, patch) => {
+            const result = await db.query(sql `select * from ${table} where id = ${id}`);
+            const row = result.rows[0];
+            if (row === undefined)
+                throw keyNotFound();
+            if (patch.scope !== undefined)
+                assertScope(patch.scope);
+            const name = patch.name ?? row.name;
+            const scopeJson = patch.scope === undefined ? row.scope : JSON.stringify(patch.scope);
+            const rateLimitPerMinute = patch.rateLimitPerMinute === undefined
+                ? row.rate_limit_per_minute
+                : patch.rateLimitPerMinute;
+            await db.query(sql `
+        update ${table}
+        set name = ${name}, scope = ${scopeJson}, rate_limit_per_minute = ${rateLimitPerMinute}
+        where id = ${id}`);
+            return fromRow({
+                ...row,
+                name,
+                scope: scopeJson,
+                rate_limit_per_minute: rateLimitPerMinute,
+            });
+        },
         revoke: async (id) => {
             const revokedAt = new Date(now()).toISOString();
             await db.query(sql `update ${table} set revoked_at = ${revokedAt} where id = ${id} and revoked_at is null`);
         },
+        purge: async (id) => {
+            const result = await db.query(sql `select * from ${table} where id = ${id}`);
+            const row = result.rows[0];
+            if (row === undefined)
+                throw keyNotFound();
+            if (row.revoked_at === null) {
+                throw new CogentaError({
+                    code: 'API_KEY_PURGE_INVALID',
+                    message: 'Only a revoked key can be purged.',
+                    hint: 'Revoke this key first if it should no longer exist at all.',
+                });
+            }
+            const revokedAgoMs = now() - new Date(row.revoked_at).getTime();
+            const minAgeMs = MIN_PURGE_AFTER_REVOKED_DAYS * 24 * 60 * 60 * 1000;
+            if (revokedAgoMs < minAgeMs) {
+                throw new CogentaError({
+                    code: 'API_KEY_PURGE_INVALID',
+                    message: `A revoked key can only be purged after ${MIN_PURGE_AFTER_REVOKED_DAYS} days.`,
+                    hint: 'Wait for the retention window to pass, or leave it revoked — a revoked key can never authenticate again.',
+                });
+            }
+            // Its usage history first: nothing references it by foreign key, but a
+            // dangling row for a key id that no longer exists would only ever be
+            // dead weight, never something `usage()` is asked about again.
+            await db.query(sql `delete from ${usageTable} where key_id = ${id}`);
+            await db.query(sql `delete from ${table} where id = ${id}`);
+        },
+        recover: async (id) => {
+            const result = await db.query(sql `select * from ${table} where id = ${id}`);
+            const row = result.rows[0];
+            if (row === undefined)
+                throw keyNotFound();
+            if (row.revoked_at === null) {
+                throw new CogentaError({
+                    code: 'API_KEY_RECOVERY_INVALID',
+                    message: 'Only a revoked key can be recovered — an active key should be rotated instead.',
+                    hint: 'Use rotate() for a key that is still active.',
+                });
+            }
+            const revokedAgoMs = now() - new Date(row.revoked_at).getTime();
+            if (revokedAgoMs > RECOVERY_WINDOW_MS) {
+                throw new CogentaError({
+                    code: 'API_KEY_RECOVERY_INVALID',
+                    message: `This key was revoked more than ${RECOVERY_WINDOW_MS / (60 * 60 * 1000)} hours ago — recovery is only for a very recent, mistaken revocation.`,
+                    hint: 'Create a brand new key instead. The revoked key stays revoked either way.',
+                });
+            }
+            const scope = JSON.parse(row.scope);
+            const rateLimitPerMinute = row.rate_limit_per_minute ?? DEFAULT_RATE_LIMIT_PER_MINUTE;
+            const currentTime = now();
+            // Same duration-preserving policy as rotate(): a replacement for a key
+            // that never expired keeps not expiring, and one that had a fixed
+            // lifetime gets that same duration, restarted from now.
+            const expiresAt = row.expires_at === null
+                ? undefined
+                : new Date(currentTime +
+                    Math.max(new Date(row.expires_at).getTime() - new Date(row.created_at).getTime(), 0)).toISOString();
+            const issued = await create({
+                name: row.name,
+                scope,
+                createdBy: row.created_by,
+                rateLimitPerMinute,
+                ...(expiresAt === undefined ? {} : { expiresAt }),
+            });
+            // `revoked_at` is deliberately never touched: the row this recovers
+            // from stays revoked forever, exactly as decision (b) in fiche 62 §3
+            // requires. `superseded_by` only records what replaced it, the same
+            // way rotation already links a live key to what came after it.
+            await db.query(sql `update ${table} set superseded_by = ${issued.id} where id = ${id}`);
+            return issued;
+        },
         verify: async (rawKey) => {
             if (!looksLikeApiKey(rawKey))
                 return null;
@@ -105,8 +268,78 @@ export function createApiKeyStore(db, now = Date.now) {
                 return null;
             const lastUsedAt = new Date(now()).toISOString();
             await db.query(sql `update ${table} set last_used_at = ${lastUsedAt} where id = ${row.id}`);
+            await recordUsage(row.id);
             return fromRow({ ...row, last_used_at: lastUsedAt });
         },
+        rotate: async (id, options) => {
+            const result = await db.query(sql `select * from ${table} where id = ${id}`);
+            const row = result.rows[0];
+            if (row === undefined)
+                throw keyNotFound();
+            if (row.revoked_at !== null) {
+                throw new CogentaError({
+                    code: 'API_KEY_ROTATION_INVALID',
+                    message: 'A revoked key cannot be rotated.',
+                    hint: 'Create a new key instead — there is nothing left to hand a grace period to.',
+                });
+            }
+            const currentTime = now();
+            if (row.expires_at !== null && new Date(row.expires_at).getTime() <= currentTime) {
+                throw new CogentaError({
+                    code: 'API_KEY_ROTATION_INVALID',
+                    message: 'An expired key cannot be rotated.',
+                    hint: 'Create a new key instead — there is nothing left to hand a grace period to.',
+                });
+            }
+            const scope = JSON.parse(row.scope);
+            const rateLimitPerMinute = row.rate_limit_per_minute ?? DEFAULT_RATE_LIMIT_PER_MINUTE;
+            // The new key's own expiry policy preserves the *duration* the old key
+            // was valid for, restarted from now — never its literal calendar date,
+            // which could already be imminent. A key that never expired keeps not
+            // expiring; nothing here invents a default the caller did not ask for.
+            const expiresAt = row.expires_at === null
+                ? undefined
+                : new Date(currentTime +
+                    Math.max(new Date(row.expires_at).getTime() - new Date(row.created_at).getTime(), 0)).toISOString();
+            const issued = await create({
+                name: row.name,
+                scope,
+                createdBy: row.created_by,
+                rateLimitPerMinute,
+                ...(expiresAt === undefined ? {} : { expiresAt }),
+            });
+            // The old key's grace window: it keeps working until whichever comes
+            // first, its own existing expiry or the chosen grace period — rotating
+            // a key that was about to expire tomorrow must not grant it another
+            // week.
+            const graceExpiry = new Date(currentTime + options.graceMs).toISOString();
+            const previousExpiresAt = row.expires_at !== null && row.expires_at < graceExpiry ? row.expires_at : graceExpiry;
+            await db.query(sql `
+        update ${table} set expires_at = ${previousExpiresAt}, superseded_by = ${issued.id}
+        where id = ${id}`);
+            return {
+                issued,
+                previous: fromRow({
+                    ...row,
+                    expires_at: previousExpiresAt,
+                    superseded_by: issued.id,
+                }),
+            };
+        },
+        usage: async (id) => {
+            const since30 = dayKey(now() - 29 * 24 * 60 * 60 * 1000);
+            const since7 = dayKey(now() - 6 * 24 * 60 * 60 * 1000);
+            const result = await db.query(sql `select day, count from ${usageTable} where key_id = ${id} and day >= ${since30}`);
+            let last7Days = 0;
+            let last30Days = 0;
+            for (const row of result.rows) {
+                const count = Number(row.count);
+                last30Days += count;
+                if (row.day >= since7)
+                    last7Days += count;
+            }
+            return { last7Days, last30Days };
+        },
     };
 }
 //# sourceMappingURL=api-keys.js.map

package/dist/api-keys.js.map

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

package/dist/audit-integrity.d.ts

@@ -0,0 +1,61 @@
+import { type DatabaseHandle } from '@cogenta/core';
+import type { AuditChainPoint, AuditLog } from './audit.js';
+/**
+ * Fiche 21 task 3: "un bouton qu'on ne presse jamais ne protège de rien" — a
+ * scheduled counterpart to the manual "verify now" button, with somewhere to
+ * remember what it last found so the admin screen can say "checked 40
+ * seconds ago, chain intact" without replaying the whole log to answer that.
+ *
+ * Two things this store is careful about:
+ *  - **Bounded.** Most runs are `audit.verifyRange(checkpoint)`, not
+ *    `audit.verify()` — a million-entry log cannot be replayed on every
+ *    tick. A full replay still happens periodically (`fullCheckIntervalMs`,
+ *    a week by default) as the "vérification complète plus rare en secours"
+ *    the fiche asks for, because an incremental check can only prove the
+ *    *suffix* since the last checkpoint is intact — it does not re-read
+ *    entries before it, so tampering with already-checkpointed history is
+ *    only ever caught by a full run.
+ *  - **Sticky once broken.** A break is not quietly retried away: once
+ *    `state` is `'broken'`, only an explicit `check({ full: true })` (the
+ *    admin's own "verify now", or an operator who has since pruned the bad
+ *    prefix) attempts to move past it. Every other tick just re-stamps
+ *    `lastCheckedAt` so "still checking" is visible without pretending the
+ *    problem went away on its own.
+ */
+export type AuditIntegrityMode = 'incremental' | 'full';
+export type AuditIntegrityState = 'never-run' | 'ok' | 'broken';
+export interface AuditIntegrityStatus {
+    readonly state: AuditIntegrityState;
+    readonly checkpoint: AuditChainPoint | null;
+    readonly entriesChecked: number;
+    readonly lastCheckedAt: string | null;
+    readonly lastMode: AuditIntegrityMode | null;
+    readonly lastFullCheckedAt: string | null;
+    readonly brokenAt: string | null;
+    readonly brokenEntryId: string | null;
+    readonly brokenMessage: string | null;
+}
+export interface AuditIntegrityCheckResult {
+    readonly status: AuditIntegrityStatus;
+    /**
+     * `true` only on the run that first found the chain broken — the signal
+     * an alert-sending caller should use to actually send one, rather than
+     * re-alerting on every subsequent tick while the same break stands.
+     */
+    readonly newlyBroken: boolean;
+}
+export interface AuditIntegrityStore {
+    /** Reads the last outcome without running a new check — cheap, one row. */
+    status(): Promise<AuditIntegrityStatus>;
+    /** Runs a check now. `full: true` forces a full replay instead of the usual incremental one — also what re-attempts past a `'broken'` state. */
+    check(options?: {
+        readonly full?: boolean;
+    }): Promise<AuditIntegrityCheckResult>;
+}
+export interface AuditIntegrityOptions {
+    readonly now?: () => number;
+    /** How rarely a full replay runs on its own. Default: 7 days. */
+    readonly fullCheckIntervalMs?: number;
+}
+export declare function createAuditIntegrityStore(db: DatabaseHandle, audit: Pick<AuditLog, 'verifyRange'>, options?: AuditIntegrityOptions): AuditIntegrityStore;
+//# sourceMappingURL=audit-integrity.d.ts.map

package/dist/audit-integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-integrity.d.ts","sourceRoot":"","sources":["../src/audit-integrity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAmC,MAAM,eAAe,CAAA;AACpF,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAG3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,MAAM,CAAA;AACvD,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,IAAI,GAAG,QAAQ,CAAA;AAE/D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;IACnC,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI,CAAA;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAA;IAC5C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CACtC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;IACrC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,MAAM,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACvC,gJAAgJ;IAChJ,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAA;CACjF;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACtC;AA4DD,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,EACpC,OAAO,GAAE,qBAA0B,GAClC,mBAAmB,CAiGrB"}