@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/analytics-retention.js

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Retention for the AGL-82 analytics day docs (AGL-1844).
+ *
+ * Day docs accumulated forever: every pageview, media serve and redirect hit
+ * left a `{hosts|orgs}/{id}/analytics/{YYYY-MM-DD}` (or
+ * `hosts/{id}/screenAnalytics/{screenId}:{day}`) document behind, and
+ * nothing ever deleted one. Every WRITER now stamps `expiresAt`, and a
+ * Firestore TTL policy on that field (declared as `fieldOverrides` in
+ * `cloud/firebase-firestore.indexes.json`, on the `analytics` and
+ * `screenAnalytics` collection groups) sweeps the old ones.
+ *
+ * ## Why 400 days
+ *
+ * Long enough that every reader's window closes with room to spare:
+ *
+ * - the console's widest range is 90 days;
+ * - /api/billing/report-usage meters `analytics/{day}.total` for the CURRENT
+ *   period — an invoice dispute a year later still finds its days;
+ * - a year-over-year comparison (no surface does one yet) would still have
+ *   both years.
+ *
+ * Short enough that storage is bounded: ~400 docs per host (plus per-screen
+ * and per-org docs) at steady state, instead of unbounded growth.
+ *
+ * ## Why TTL and NOT monthly rollups (the AGL-1844 decision)
+ *
+ * Rollups were considered and deliberately not built: no console surface
+ * reads more than 90 dailies (bounded, and blunted by the AGL-1440 cache),
+ * so a monthly doc would be written by a scheduled job — new moving part,
+ * new failure mode — to serve a view nothing renders. If a >90-day console
+ * range ever ships, rollups become that feature's first commit.
+ *
+ * TTL deletion is Firestore's own sweeper: typically within 24h of expiry,
+ * no code of ours runs. Docs written BEFORE this shipped carry no
+ * `expiresAt` and are never swept — the trickle of writes to a live site
+ * stamps its recent days naturally, and old unstamped days are exactly the
+ * ones nothing reads.
+ */ /** See the module doc for why 400. */ export const ANALYTICS_DAY_RETENTION_DAYS = 400;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * When the day doc named `day` (YYYY-MM-DD, UTC) may be swept. Anchored on
+ * the day itself, not the write clock, so every write to one doc agrees on
+ * one expiry. An unparsable day anchors on "now", which only ever shortens
+ * retention.
+ */ export function analyticsDayExpiresAt(day) {
+    const dayStart = Date.parse(`${day}T00:00:00Z`);
+    const base = Number.isFinite(dayStart) ? dayStart : Date.now();
+    return new Date(base + ANALYTICS_DAY_RETENTION_DAYS * DAY_MS);
+}
+
+//# sourceMappingURL=analytics-retention.js.map

package/src/lib/server/analytics-retention.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/analytics-retention.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Retention for the AGL-82 analytics day docs (AGL-1844).\n *\n * Day docs accumulated forever: every pageview, media serve and redirect hit\n * left a `{hosts|orgs}/{id}/analytics/{YYYY-MM-DD}` (or\n * `hosts/{id}/screenAnalytics/{screenId}:{day}`) document behind, and\n * nothing ever deleted one. Every WRITER now stamps `expiresAt`, and a\n * Firestore TTL policy on that field (declared as `fieldOverrides` in\n * `cloud/firebase-firestore.indexes.json`, on the `analytics` and\n * `screenAnalytics` collection groups) sweeps the old ones.\n *\n * ## Why 400 days\n *\n * Long enough that every reader's window closes with room to spare:\n *\n * - the console's widest range is 90 days;\n * - /api/billing/report-usage meters `analytics/{day}.total` for the CURRENT\n *   period — an invoice dispute a year later still finds its days;\n * - a year-over-year comparison (no surface does one yet) would still have\n *   both years.\n *\n * Short enough that storage is bounded: ~400 docs per host (plus per-screen\n * and per-org docs) at steady state, instead of unbounded growth.\n *\n * ## Why TTL and NOT monthly rollups (the AGL-1844 decision)\n *\n * Rollups were considered and deliberately not built: no console surface\n * reads more than 90 dailies (bounded, and blunted by the AGL-1440 cache),\n * so a monthly doc would be written by a scheduled job — new moving part,\n * new failure mode — to serve a view nothing renders. If a >90-day console\n * range ever ships, rollups become that feature's first commit.\n *\n * TTL deletion is Firestore's own sweeper: typically within 24h of expiry,\n * no code of ours runs. Docs written BEFORE this shipped carry no\n * `expiresAt` and are never swept — the trickle of writes to a live site\n * stamps its recent days naturally, and old unstamped days are exactly the\n * ones nothing reads.\n */\n\n/** See the module doc for why 400. */\nexport const ANALYTICS_DAY_RETENTION_DAYS = 400\n\nconst DAY_MS = 24 * 60 * 60 * 1000\n\n/**\n * When the day doc named `day` (YYYY-MM-DD, UTC) may be swept. Anchored on\n * the day itself, not the write clock, so every write to one doc agrees on\n * one expiry. An unparsable day anchors on \"now\", which only ever shortens\n * retention.\n */\nexport function analyticsDayExpiresAt(day: string): Date {\n  const dayStart = Date.parse(`${day}T00:00:00Z`)\n  const base = Number.isFinite(dayStart) ? dayStart : Date.now()\n  return new Date(base + ANALYTICS_DAY_RETENTION_DAYS * DAY_MS)\n}\n"],"names":["ANALYTICS_DAY_RETENTION_DAYS","DAY_MS","analyticsDayExpiresAt","day","dayStart","Date","parse","base","Number","isFinite","now"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCC,GAED,oCAAoC,GACpC,OAAO,MAAMA,+BAA+B,IAAG;AAE/C,MAAMC,SAAS,KAAK,KAAK,KAAK;AAE9B;;;;;CAKC,GACD,OAAO,SAASC,sBAAsBC,GAAW;IAC/C,MAAMC,WAAWC,KAAKC,KAAK,CAAC,GAAGH,IAAI,UAAU,CAAC;IAC9C,MAAMI,OAAOC,OAAOC,QAAQ,CAACL,YAAYA,WAAWC,KAAKK,GAAG;IAC5D,OAAO,IAAIL,KAAKE,OAAOP,+BAA+BC;AACxD"}

package/src/lib/server/api-http.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * HTTP building blocks for the customer REST API (`/api/v1`, AGL-617): a
+ * consistent JSON error envelope, list/pagination helpers, and a per-key
+ * rate limiter. Everything here is pure (Web `Response` + plain data), so it
+ * is unit-tested directly.
+ */
+/** Every error response is `{ error: { type, message, code?, fields? } }`. */
+export interface ApiErrorBody {
+    error: {
+        type: string;
+        message: string;
+        code?: string;
+        /** Per-field reasons on a validation failure (AGL-901). */
+        fields?: Record<string, string>;
+    };
+}
+export interface ApiResponseInit {
+    message?: string;
+    code?: string;
+    /**
+     * Field id → reason, surfaced on `validation_failed`. Additive: clients
+     * that only read `type`/`message` are unaffected.
+     */
+    fields?: Record<string, string>;
+    headers?: Record<string, string>;
+}
+/** Canonical error responses. Pass `{ headers }` to carry rate-limit headers. */
+export declare const ApiErrors: {
+    unauthorized: (init?: ApiResponseInit) => Response;
+    planRequired: (init?: ApiResponseInit) => Response;
+    insufficientScope: (scope: string, headers?: Record<string, string>) => Response;
+    forbidden: (init?: ApiResponseInit) => Response;
+    notFound: (init?: ApiResponseInit) => Response;
+    badRequest: (init?: ApiResponseInit) => Response;
+    /**
+     * The request conflicts with work already in flight (AGL-1709). Used by the
+     * idempotency claim for the one case it must fail CLOSED: an identical
+     * attempt that has taken the claim but not yet settled. Letting the second
+     * caller through is the duplicate the key exists to prevent, so it is
+     * refused rather than served — and a client that reads `type` gets a
+     * retriable answer rather than a mystery.
+     */
+    conflict: (init?: ApiResponseInit) => Response;
+    methodNotAllowed: (init?: ApiResponseInit) => Response;
+    /**
+     * The three refusals an upload can produce that a JSON-only API never could
+     * (AGL-2463). Built here rather than at the call site so `/v1` keeps ONE
+     * error envelope — a client branching on `error.type` must not meet a bare
+     * `{ error: '<sentence>' }` on the one surface that handles bytes.
+     */
+    unsupportedMediaType: (init?: ApiResponseInit) => Response;
+    payloadTooLarge: (init?: ApiResponseInit) => Response;
+    /**
+     * 451, matching the console's own media chokepoints: the asset is refused
+     * because its content hash is on the takedown ledger, which is a legal
+     * verdict rather than a permission or a quota.
+     */
+    unavailableForLegalReasons: (init?: ApiResponseInit) => Response;
+    rateLimited: (retryAfterSec: number, headers?: Record<string, string>) => Response;
+    internal: (init?: ApiResponseInit) => Response;
+};
+/**
+ * Re-emit `response` with `headers` merged in — the escape hatch for a
+ * refusal built by a shared helper that knows nothing about this request's
+ * rate-limit budget (the lockdown 423, AGL-1596). Status, body and the
+ * response's own headers are preserved; `set` overwrites rather than
+ * appends, so a header named on both sides appears exactly once (the passed
+ * value wins) and no client ever reads a doubled `X-RateLimit-Remaining`.
+ */
+export declare function withResponseHeaders(response: Response, headers: Record<string, string>): Response;
+/** Success JSON with an optional status + headers (e.g. rate-limit headers). */
+export declare function apiJson(data: unknown, init?: {
+    status?: number;
+    headers?: Record<string, string>;
+}): Response;
+export declare const DEFAULT_PAGE_LIMIT = 25;
+export declare const MAX_PAGE_LIMIT = 100;
+/** Clamp a `?limit=` value to [1, MAX], defaulting when absent/invalid. */
+export declare function parseLimit(raw: string | null | undefined): number;
+/** Opaque cursor = base64url of an underlying key (e.g. a Firestore doc id). */
+export declare function encodeCursor(value: string): string;
+export declare function decodeCursor(cursor: string | null | undefined): string | undefined;
+/** List envelope: `{ data, next_cursor, has_more }`. */
+export declare function listResponse(data: unknown[], nextCursor: string | null, headers?: Record<string, string>): Response;
+export interface RateLimitState {
+    count: number;
+    windowStartMs: number;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    resetMs: number;
+}
+export interface RateLimitOptions {
+    limit?: number;
+    windowMs?: number;
+    now?: number;
+    store?: Map<string, RateLimitState>;
+}
+export declare const DEFAULT_RATE_LIMIT = 120;
+export declare const DEFAULT_RATE_WINDOW_MS = 60000;
+/** Count one request against `key`'s fixed window. `now`/`store` injectable. */
+export declare function checkRateLimit(key: string, options?: RateLimitOptions): RateLimitResult;
+/**
+ * Report `key`'s window WITHOUT counting a request against it (AGL-2414).
+ *
+ * `checkRateLimit` fuses "is there budget" with "spend some", which is the
+ * right shape when every call is a request to be counted. It is the wrong
+ * shape when the budget meters something the caller has not done *yet* and
+ * may never do — `/api/v1` gates the Firestore key lookup on an IP's budget
+ * of *unproductive* lookups, so it has to ask before the lookup and only
+ * charge if the lookup came back empty. Asking with `checkRateLimit` would
+ * charge every request, including the successful ones, which is precisely the
+ * customer-visible cap that budget must not become.
+ *
+ * `allowed` answers "would the NEXT call be admitted", i.e. `count < limit` —
+ * one off from `checkRateLimit`'s post-increment `count <= limit`, and the
+ * same verdict for the same request. `remaining` is what is left now, so an
+ * untouched or expired window reports the full `limit` rather than
+ * `limit - 1`.
+ */
+export declare function peekRateLimit(key: string, options?: RateLimitOptions): RateLimitResult;
+/**
+ * Rate-limit headers, in BOTH spellings (AGL-2727).
+ *
+ * `X-RateLimit-*` is the de-facto set this API has always sent, and it is kept
+ * verbatim — including `Reset` as an epoch second — because integrations are
+ * already reading it and a header that changes meaning under a client is worse
+ * than one it has to learn.
+ *
+ * `RateLimit-*` is RFC 9331, which is what a caller that was not written
+ * against this specific API looks for, and increasingly what an agent looks
+ * for. Same numbers, standard spelling. Its `Reset` is SECONDS REMAINING, not
+ * an epoch — that is the RFC's own choice, and the better one: a duration is
+ * read against the caller's clock rather than ours, so a skewed clock cannot
+ * turn "wait 12 seconds" into "wait until 1970".
+ *
+ * ⚠️ Both are computed from the SAME `result`, so they can never disagree.
+ * Two independently-derived budgets on one response is a bug that reads as a
+ * rounding error.
+ */
+export declare function rateLimitHeaders(result: RateLimitResult, now?: number): Record<string, string>;

package/src/lib/server/api-http.js

@@ -0,0 +1,230 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * HTTP building blocks for the customer REST API (`/api/v1`, AGL-617): a
+ * consistent JSON error envelope, list/pagination helpers, and a per-key
+ * rate limiter. Everything here is pure (Web `Response` + plain data), so it
+ * is unit-tested directly.
+ */ /** Every error response is `{ error: { type, message, code?, fields? } }`. */ import { _ as _extends } from "@swc/helpers/_/_extends";
+function errorResponse(status, type, fallbackMessage, init) {
+    var _ref;
+    const error = {
+        type,
+        message: (_ref = init == null ? void 0 : init.message) != null ? _ref : fallbackMessage
+    };
+    if (init == null ? void 0 : init.code) error.code = init.code;
+    if ((init == null ? void 0 : init.fields) && Object.keys(init.fields).length) error.fields = init.fields;
+    return Response.json({
+        error
+    }, {
+        status,
+        headers: init == null ? void 0 : init.headers
+    });
+}
+/** Canonical error responses. Pass `{ headers }` to carry rate-limit headers. */ export const ApiErrors = {
+    unauthorized: (init)=>errorResponse(401, 'unauthorized', 'Invalid or missing API key', init),
+    planRequired: (init)=>errorResponse(403, 'plan_required', 'API access requires the Business or Advanced plan', init),
+    insufficientScope: (scope, headers)=>errorResponse(403, 'insufficient_scope', `Missing the "${scope}" scope`, {
+            code: scope,
+            headers
+        }),
+    forbidden: (init)=>errorResponse(403, 'forbidden', 'Not permitted', init),
+    notFound: (init)=>errorResponse(404, 'not_found', 'Not found', init),
+    badRequest: (init)=>errorResponse(400, 'bad_request', 'Bad request', init),
+    /**
+   * The request conflicts with work already in flight (AGL-1709). Used by the
+   * idempotency claim for the one case it must fail CLOSED: an identical
+   * attempt that has taken the claim but not yet settled. Letting the second
+   * caller through is the duplicate the key exists to prevent, so it is
+   * refused rather than served — and a client that reads `type` gets a
+   * retriable answer rather than a mystery.
+   */ conflict: (init)=>errorResponse(409, 'conflict', 'Conflicts with the current state', init),
+    methodNotAllowed: (init)=>errorResponse(405, 'method_not_allowed', 'Method not allowed', init),
+    /**
+   * The three refusals an upload can produce that a JSON-only API never could
+   * (AGL-2463). Built here rather than at the call site so `/v1` keeps ONE
+   * error envelope — a client branching on `error.type` must not meet a bare
+   * `{ error: '<sentence>' }` on the one surface that handles bytes.
+   */ unsupportedMediaType: (init)=>errorResponse(415, 'unsupported_media_type', 'Unsupported file type', init),
+    payloadTooLarge: (init)=>errorResponse(413, 'payload_too_large', 'File too large', init),
+    /**
+   * 451, matching the console's own media chokepoints: the asset is refused
+   * because its content hash is on the takedown ledger, which is a legal
+   * verdict rather than a permission or a quota.
+   */ unavailableForLegalReasons: (init)=>errorResponse(451, 'unavailable_for_legal_reasons', 'This file has been removed and cannot be uploaded', init),
+    rateLimited: (retryAfterSec, headers)=>errorResponse(429, 'rate_limited', 'Too many requests', {
+            headers: _extends({
+                'Retry-After': String(Math.max(1, retryAfterSec))
+            }, headers)
+        }),
+    internal: (init)=>errorResponse(500, 'internal_error', 'Something went wrong', init)
+};
+/**
+ * Re-emit `response` with `headers` merged in — the escape hatch for a
+ * refusal built by a shared helper that knows nothing about this request's
+ * rate-limit budget (the lockdown 423, AGL-1596). Status, body and the
+ * response's own headers are preserved; `set` overwrites rather than
+ * appends, so a header named on both sides appears exactly once (the passed
+ * value wins) and no client ever reads a doubled `X-RateLimit-Remaining`.
+ */ export function withResponseHeaders(response, headers) {
+    const merged = new Headers(response.headers);
+    for (const [name, value] of Object.entries(headers))merged.set(name, value);
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: merged
+    });
+}
+/** Success JSON with an optional status + headers (e.g. rate-limit headers). */ export function apiJson(data, init) {
+    var _ref;
+    return Response.json(data, {
+        status: (_ref = init == null ? void 0 : init.status) != null ? _ref : 200,
+        headers: init == null ? void 0 : init.headers
+    });
+}
+// ── Pagination ──────────────────────────────────────────────────────────────
+export const DEFAULT_PAGE_LIMIT = 25;
+export const MAX_PAGE_LIMIT = 100;
+/** Clamp a `?limit=` value to [1, MAX], defaulting when absent/invalid. */ export function parseLimit(raw) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1) return DEFAULT_PAGE_LIMIT;
+    return Math.min(Math.floor(n), MAX_PAGE_LIMIT);
+}
+/** Opaque cursor = base64url of an underlying key (e.g. a Firestore doc id). */ export function encodeCursor(value) {
+    return Buffer.from(value, 'utf8').toString('base64url');
+}
+export function decodeCursor(cursor) {
+    if (!cursor) return undefined;
+    try {
+        const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+        return decoded.length > 0 ? decoded : undefined;
+    } catch (unused) {
+        return undefined;
+    }
+}
+/** List envelope: `{ data, next_cursor, has_more }`. */ export function listResponse(data, nextCursor, headers) {
+    return apiJson({
+        object: 'list',
+        data,
+        next_cursor: nextCursor,
+        has_more: nextCursor != null
+    }, {
+        headers
+    });
+}
+export const DEFAULT_RATE_LIMIT = 120;
+export const DEFAULT_RATE_WINDOW_MS = 60000;
+// Per-instance store. Serverless instances are ephemeral, so this blunts
+// bursts rather than enforcing a global cap (matches the app's other
+// limiters); a durable per-key counter can back it later.
+const defaultStore = new Map();
+/** Count one request against `key`'s fixed window. `now`/`store` injectable. */ export function checkRateLimit(key, options) {
+    var _ref, _ref1, _ref2, _ref3;
+    const limit = (_ref = options == null ? void 0 : options.limit) != null ? _ref : DEFAULT_RATE_LIMIT;
+    const windowMs = (_ref1 = options == null ? void 0 : options.windowMs) != null ? _ref1 : DEFAULT_RATE_WINDOW_MS;
+    const now = (_ref2 = options == null ? void 0 : options.now) != null ? _ref2 : Date.now();
+    const store = (_ref3 = options == null ? void 0 : options.store) != null ? _ref3 : defaultStore;
+    const state = store.get(key);
+    if (!state || now - state.windowStartMs >= windowMs) {
+        store.set(key, {
+            count: 1,
+            windowStartMs: now
+        });
+        return {
+            allowed: true,
+            limit,
+            remaining: limit - 1,
+            resetMs: now + windowMs
+        };
+    }
+    state.count += 1;
+    return {
+        allowed: state.count <= limit,
+        limit,
+        remaining: Math.max(0, limit - state.count),
+        resetMs: state.windowStartMs + windowMs
+    };
+}
+/**
+ * Report `key`'s window WITHOUT counting a request against it (AGL-2414).
+ *
+ * `checkRateLimit` fuses "is there budget" with "spend some", which is the
+ * right shape when every call is a request to be counted. It is the wrong
+ * shape when the budget meters something the caller has not done *yet* and
+ * may never do — `/api/v1` gates the Firestore key lookup on an IP's budget
+ * of *unproductive* lookups, so it has to ask before the lookup and only
+ * charge if the lookup came back empty. Asking with `checkRateLimit` would
+ * charge every request, including the successful ones, which is precisely the
+ * customer-visible cap that budget must not become.
+ *
+ * `allowed` answers "would the NEXT call be admitted", i.e. `count < limit` —
+ * one off from `checkRateLimit`'s post-increment `count <= limit`, and the
+ * same verdict for the same request. `remaining` is what is left now, so an
+ * untouched or expired window reports the full `limit` rather than
+ * `limit - 1`.
+ */ export function peekRateLimit(key, options) {
+    var _ref, _ref1, _ref2, _ref3;
+    const limit = (_ref = options == null ? void 0 : options.limit) != null ? _ref : DEFAULT_RATE_LIMIT;
+    const windowMs = (_ref1 = options == null ? void 0 : options.windowMs) != null ? _ref1 : DEFAULT_RATE_WINDOW_MS;
+    const now = (_ref2 = options == null ? void 0 : options.now) != null ? _ref2 : Date.now();
+    const store = (_ref3 = options == null ? void 0 : options.store) != null ? _ref3 : defaultStore;
+    const state = store.get(key);
+    if (!state || now - state.windowStartMs >= windowMs) {
+        return {
+            allowed: true,
+            limit,
+            remaining: limit,
+            resetMs: now + windowMs
+        };
+    }
+    return {
+        allowed: state.count < limit,
+        limit,
+        remaining: Math.max(0, limit - state.count),
+        resetMs: state.windowStartMs + windowMs
+    };
+}
+/**
+ * Rate-limit headers, in BOTH spellings (AGL-2727).
+ *
+ * `X-RateLimit-*` is the de-facto set this API has always sent, and it is kept
+ * verbatim — including `Reset` as an epoch second — because integrations are
+ * already reading it and a header that changes meaning under a client is worse
+ * than one it has to learn.
+ *
+ * `RateLimit-*` is RFC 9331, which is what a caller that was not written
+ * against this specific API looks for, and increasingly what an agent looks
+ * for. Same numbers, standard spelling. Its `Reset` is SECONDS REMAINING, not
+ * an epoch — that is the RFC's own choice, and the better one: a duration is
+ * read against the caller's clock rather than ours, so a skewed clock cannot
+ * turn "wait 12 seconds" into "wait until 1970".
+ *
+ * ⚠️ Both are computed from the SAME `result`, so they can never disagree.
+ * Two independently-derived budgets on one response is a bug that reads as a
+ * rounding error.
+ */ export function rateLimitHeaders(result, now = Date.now()) {
+    const remainingSeconds = Math.max(0, Math.ceil((result.resetMs - now) / 1000));
+    return {
+        'X-RateLimit-Limit': String(result.limit),
+        'X-RateLimit-Remaining': String(result.remaining),
+        'X-RateLimit-Reset': String(Math.ceil(result.resetMs / 1000)),
+        'RateLimit-Limit': String(result.limit),
+        'RateLimit-Remaining': String(result.remaining),
+        'RateLimit-Reset': String(remainingSeconds)
+    };
+}
+
+//# sourceMappingURL=api-http.js.map

package/src/lib/server/api-http.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/api-http.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * HTTP building blocks for the customer REST API (`/api/v1`, AGL-617): a\n * consistent JSON error envelope, list/pagination helpers, and a per-key\n * rate limiter. Everything here is pure (Web `Response` + plain data), so it\n * is unit-tested directly.\n */\n\n/** Every error response is `{ error: { type, message, code?, fields? } }`. */\nexport interface ApiErrorBody {\n  error: {\n    type: string\n    message: string\n    code?: string\n    /** Per-field reasons on a validation failure (AGL-901). */\n    fields?: Record<string, string>\n  }\n}\n\nexport interface ApiResponseInit {\n  message?: string\n  code?: string\n  /**\n   * Field id → reason, surfaced on `validation_failed`. Additive: clients\n   * that only read `type`/`message` are unaffected.\n   */\n  fields?: Record<string, string>\n  headers?: Record<string, string>\n}\n\nfunction errorResponse(\n  status: number,\n  type: string,\n  fallbackMessage: string,\n  init?: ApiResponseInit,\n): Response {\n  const error: ApiErrorBody['error'] = {\n    type,\n    message: init?.message ?? fallbackMessage,\n  }\n  if (init?.code) error.code = init.code\n  if (init?.fields && Object.keys(init.fields).length) error.fields = init.fields\n  return Response.json({ error }, { status, headers: init?.headers })\n}\n\n/** Canonical error responses. Pass `{ headers }` to carry rate-limit headers. */\nexport const ApiErrors = {\n  unauthorized: (init?: ApiResponseInit) =>\n    errorResponse(401, 'unauthorized', 'Invalid or missing API key', init),\n  planRequired: (init?: ApiResponseInit) =>\n    errorResponse(\n      403,\n      'plan_required',\n      'API access requires the Business or Advanced plan',\n      init,\n    ),\n  insufficientScope: (scope: string, headers?: Record<string, string>) =>\n    errorResponse(403, 'insufficient_scope', `Missing the \"${scope}\" scope`, {\n      code: scope,\n      headers,\n    }),\n  forbidden: (init?: ApiResponseInit) =>\n    errorResponse(403, 'forbidden', 'Not permitted', init),\n  notFound: (init?: ApiResponseInit) =>\n    errorResponse(404, 'not_found', 'Not found', init),\n  badRequest: (init?: ApiResponseInit) =>\n    errorResponse(400, 'bad_request', 'Bad request', init),\n  /**\n   * The request conflicts with work already in flight (AGL-1709). Used by the\n   * idempotency claim for the one case it must fail CLOSED: an identical\n   * attempt that has taken the claim but not yet settled. Letting the second\n   * caller through is the duplicate the key exists to prevent, so it is\n   * refused rather than served — and a client that reads `type` gets a\n   * retriable answer rather than a mystery.\n   */\n  conflict: (init?: ApiResponseInit) =>\n    errorResponse(409, 'conflict', 'Conflicts with the current state', init),\n  methodNotAllowed: (init?: ApiResponseInit) =>\n    errorResponse(405, 'method_not_allowed', 'Method not allowed', init),\n  /**\n   * The three refusals an upload can produce that a JSON-only API never could\n   * (AGL-2463). Built here rather than at the call site so `/v1` keeps ONE\n   * error envelope — a client branching on `error.type` must not meet a bare\n   * `{ error: '<sentence>' }` on the one surface that handles bytes.\n   */\n  unsupportedMediaType: (init?: ApiResponseInit) =>\n    errorResponse(415, 'unsupported_media_type', 'Unsupported file type', init),\n  payloadTooLarge: (init?: ApiResponseInit) =>\n    errorResponse(413, 'payload_too_large', 'File too large', init),\n  /**\n   * 451, matching the console's own media chokepoints: the asset is refused\n   * because its content hash is on the takedown ledger, which is a legal\n   * verdict rather than a permission or a quota.\n   */\n  unavailableForLegalReasons: (init?: ApiResponseInit) =>\n    errorResponse(\n      451,\n      'unavailable_for_legal_reasons',\n      'This file has been removed and cannot be uploaded',\n      init,\n    ),\n  rateLimited: (retryAfterSec: number, headers?: Record<string, string>) =>\n    errorResponse(429, 'rate_limited', 'Too many requests', {\n      headers: { 'Retry-After': String(Math.max(1, retryAfterSec)), ...headers },\n    }),\n  internal: (init?: ApiResponseInit) =>\n    errorResponse(500, 'internal_error', 'Something went wrong', init),\n}\n\n/**\n * Re-emit `response` with `headers` merged in — the escape hatch for a\n * refusal built by a shared helper that knows nothing about this request's\n * rate-limit budget (the lockdown 423, AGL-1596). Status, body and the\n * response's own headers are preserved; `set` overwrites rather than\n * appends, so a header named on both sides appears exactly once (the passed\n * value wins) and no client ever reads a doubled `X-RateLimit-Remaining`.\n */\nexport function withResponseHeaders(\n  response: Response,\n  headers: Record<string, string>,\n): Response {\n  const merged = new Headers(response.headers)\n  for (const [name, value] of Object.entries(headers)) merged.set(name, value)\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers: merged,\n  })\n}\n\n/** Success JSON with an optional status + headers (e.g. rate-limit headers). */\nexport function apiJson(\n  data: unknown,\n  init?: { status?: number; headers?: Record<string, string> },\n): Response {\n  return Response.json(data, {\n    status: init?.status ?? 200,\n    headers: init?.headers,\n  })\n}\n\n// ── Pagination ──────────────────────────────────────────────────────────────\n\nexport const DEFAULT_PAGE_LIMIT = 25\nexport const MAX_PAGE_LIMIT = 100\n\n/** Clamp a `?limit=` value to [1, MAX], defaulting when absent/invalid. */\nexport function parseLimit(raw: string | null | undefined): number {\n  const n = Number(raw)\n  if (!Number.isFinite(n) || n < 1) return DEFAULT_PAGE_LIMIT\n  return Math.min(Math.floor(n), MAX_PAGE_LIMIT)\n}\n\n/** Opaque cursor = base64url of an underlying key (e.g. a Firestore doc id). */\nexport function encodeCursor(value: string): string {\n  return Buffer.from(value, 'utf8').toString('base64url')\n}\n\nexport function decodeCursor(\n  cursor: string | null | undefined,\n): string | undefined {\n  if (!cursor) return undefined\n  try {\n    const decoded = Buffer.from(cursor, 'base64url').toString('utf8')\n    return decoded.length > 0 ? decoded : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/** List envelope: `{ data, next_cursor, has_more }`. */\nexport function listResponse(\n  data: unknown[],\n  nextCursor: string | null,\n  headers?: Record<string, string>,\n): Response {\n  return apiJson(\n    { object: 'list', data, next_cursor: nextCursor, has_more: nextCursor != null },\n    { headers },\n  )\n}\n\n// ── Rate limiting (fixed window, per key) ───────────────────────────────────\n\nexport interface RateLimitState {\n  count: number\n  windowStartMs: number\n}\n\nexport interface RateLimitResult {\n  allowed: boolean\n  limit: number\n  remaining: number\n  resetMs: number\n}\n\nexport interface RateLimitOptions {\n  limit?: number\n  windowMs?: number\n  now?: number\n  store?: Map<string, RateLimitState>\n}\n\nexport const DEFAULT_RATE_LIMIT = 120\nexport const DEFAULT_RATE_WINDOW_MS = 60_000\n\n// Per-instance store. Serverless instances are ephemeral, so this blunts\n// bursts rather than enforcing a global cap (matches the app's other\n// limiters); a durable per-key counter can back it later.\nconst defaultStore = new Map<string, RateLimitState>()\n\n/** Count one request against `key`'s fixed window. `now`/`store` injectable. */\nexport function checkRateLimit(\n  key: string,\n  options?: RateLimitOptions,\n): RateLimitResult {\n  const limit = options?.limit ?? DEFAULT_RATE_LIMIT\n  const windowMs = options?.windowMs ?? DEFAULT_RATE_WINDOW_MS\n  const now = options?.now ?? Date.now()\n  const store = options?.store ?? defaultStore\n\n  const state = store.get(key)\n  if (!state || now - state.windowStartMs >= windowMs) {\n    store.set(key, { count: 1, windowStartMs: now })\n    return { allowed: true, limit, remaining: limit - 1, resetMs: now + windowMs }\n  }\n  state.count += 1\n  return {\n    allowed: state.count <= limit,\n    limit,\n    remaining: Math.max(0, limit - state.count),\n    resetMs: state.windowStartMs + windowMs,\n  }\n}\n\n/**\n * Report `key`'s window WITHOUT counting a request against it (AGL-2414).\n *\n * `checkRateLimit` fuses \"is there budget\" with \"spend some\", which is the\n * right shape when every call is a request to be counted. It is the wrong\n * shape when the budget meters something the caller has not done *yet* and\n * may never do — `/api/v1` gates the Firestore key lookup on an IP's budget\n * of *unproductive* lookups, so it has to ask before the lookup and only\n * charge if the lookup came back empty. Asking with `checkRateLimit` would\n * charge every request, including the successful ones, which is precisely the\n * customer-visible cap that budget must not become.\n *\n * `allowed` answers \"would the NEXT call be admitted\", i.e. `count < limit` —\n * one off from `checkRateLimit`'s post-increment `count <= limit`, and the\n * same verdict for the same request. `remaining` is what is left now, so an\n * untouched or expired window reports the full `limit` rather than\n * `limit - 1`.\n */\nexport function peekRateLimit(\n  key: string,\n  options?: RateLimitOptions,\n): RateLimitResult {\n  const limit = options?.limit ?? DEFAULT_RATE_LIMIT\n  const windowMs = options?.windowMs ?? DEFAULT_RATE_WINDOW_MS\n  const now = options?.now ?? Date.now()\n  const store = options?.store ?? defaultStore\n\n  const state = store.get(key)\n  if (!state || now - state.windowStartMs >= windowMs) {\n    return { allowed: true, limit, remaining: limit, resetMs: now + windowMs }\n  }\n  return {\n    allowed: state.count < limit,\n    limit,\n    remaining: Math.max(0, limit - state.count),\n    resetMs: state.windowStartMs + windowMs,\n  }\n}\n\n/**\n * Rate-limit headers, in BOTH spellings (AGL-2727).\n *\n * `X-RateLimit-*` is the de-facto set this API has always sent, and it is kept\n * verbatim — including `Reset` as an epoch second — because integrations are\n * already reading it and a header that changes meaning under a client is worse\n * than one it has to learn.\n *\n * `RateLimit-*` is RFC 9331, which is what a caller that was not written\n * against this specific API looks for, and increasingly what an agent looks\n * for. Same numbers, standard spelling. Its `Reset` is SECONDS REMAINING, not\n * an epoch — that is the RFC's own choice, and the better one: a duration is\n * read against the caller's clock rather than ours, so a skewed clock cannot\n * turn \"wait 12 seconds\" into \"wait until 1970\".\n *\n * ⚠️ Both are computed from the SAME `result`, so they can never disagree.\n * Two independently-derived budgets on one response is a bug that reads as a\n * rounding error.\n */\nexport function rateLimitHeaders(\n  result: RateLimitResult,\n  now: number = Date.now(),\n): Record<string, string> {\n  const remainingSeconds = Math.max(0, Math.ceil((result.resetMs - now) / 1000))\n  return {\n    'X-RateLimit-Limit': String(result.limit),\n    'X-RateLimit-Remaining': String(result.remaining),\n    'X-RateLimit-Reset': String(Math.ceil(result.resetMs / 1000)),\n    'RateLimit-Limit': String(result.limit),\n    'RateLimit-Remaining': String(result.remaining),\n    'RateLimit-Reset': String(remainingSeconds),\n  }\n}\n"],"names":["errorResponse","status","type","fallbackMessage","init","error","message","code","fields","Object","keys","length","Response","json","headers","ApiErrors","unauthorized","planRequired","insufficientScope","scope","forbidden","notFound","badRequest","conflict","methodNotAllowed","unsupportedMediaType","payloadTooLarge","unavailableForLegalReasons","rateLimited","retryAfterSec","String","Math","max","internal","withResponseHeaders","response","merged","Headers","name","value","entries","set","body","statusText","apiJson","data","DEFAULT_PAGE_LIMIT","MAX_PAGE_LIMIT","parseLimit","raw","n","Number","isFinite","min","floor","encodeCursor","Buffer","from","toString","decodeCursor","cursor","undefined","decoded","listResponse","nextCursor","object","next_cursor","has_more","DEFAULT_RATE_LIMIT","DEFAULT_RATE_WINDOW_MS","defaultStore","Map","checkRateLimit","key","options","limit","windowMs","now","Date","store","state","get","windowStartMs","count","allowed","remaining","resetMs","peekRateLimit","rateLimitHeaders","result","remainingSeconds","ceil"],"mappings":"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"}

package/src/lib/server/api-keys.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Scopes a key can be granted, as `resource:action`. Every entry must be
+ * enforced by a real endpoint — a mintable scope that grants nothing reads
+ * as a broken permission (AGL-899 removed `contacts:write` on those grounds,
+ * and AGL-2276 re-added it in the same change that shipped the writes, which
+ * is the condition AGL-899 set).
+ */
+export declare const API_SCOPES: readonly ["datasets:read", "datasets:write", "contacts:read", "contacts:write", "sites:read", "sites:publish", "sites:write", "forms:read", "forms:write", "orders:read", "orders:write", "products:read", "media:read", "media:write", "crm:read", "crm:write"];
+export type ApiScope = (typeof API_SCOPES)[number];
+/** Live-key token prefix. A `_test_` variant can follow the same shape later. */
+export declare const API_KEY_TOKEN_PREFIX = "aglyn_sk_";
+/** Top-level collection; doc id = the token hash. */
+export declare const API_KEYS_COLLECTION = "apiKeys";
+/** Stored document. `createdAt`/`lastUsedAt`/etc. are Firestore Timestamps. */
+export interface ApiKeyDocument {
+    /** Public, stable id shown in the UI and used for revoke (never the hash). */
+    keyId: string;
+    orgId: string;
+    name: string;
+    /** e.g. `aglyn_sk_ab12cd…` — enough to recognize a key, not to use it. */
+    keyPrefix: string;
+    scopes: ApiScope[];
+    createdBy: string;
+    createdAt: FirebaseFirestore.Timestamp;
+    lastUsedAt: FirebaseFirestore.Timestamp | null;
+    revokedAt: FirebaseFirestore.Timestamp | null;
+    expiresAt: FirebaseFirestore.Timestamp | null;
+}
+/** Metadata safe to return to a client (no hash, no raw token). */
+export interface PublicApiKey {
+    keyId: string;
+    name: string;
+    keyPrefix: string;
+    scopes: ApiScope[];
+    createdAt: string | null;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    expiresAt: string | null;
+}
+/** The resolved principal after a successful key verification. */
+export interface VerifiedApiKey {
+    orgId: string;
+    keyId: string;
+    scopes: ApiScope[];
+    /**
+     * The name the organization gave the key — what a feed attributes the
+     * key's writes to (AGL-2632). Every minted key carries one; empty only
+     * for a document written before the field was required.
+     */
+    name: string;
+}
+/** True if `value` is one of the known scopes. */
+export declare function isApiScope(value: string): value is ApiScope;
+/** Keep only valid, de-duplicated scopes, preserving `API_SCOPES` order. */
+export declare function normalizeScopes(scopes: readonly string[]): ApiScope[];
+/** SHA-256 hex of a raw token — the Firestore doc id and lookup key. */
+export declare function hashApiKey(token: string): string;
+/** Structural check before hashing/looking up — cheap reject of junk input. */
+export declare function isValidApiKeyFormat(token: string): boolean;
+/**
+ * Generate a fresh token plus the derived hash and display prefix. The raw
+ * `token` is the only time the secret exists in plaintext — persist the hash,
+ * hand the token to the user once.
+ */
+export declare function generateApiKeyToken(): {
+    token: string;
+    hash: string;
+    keyPrefix: string;
+};
+/** True when the granted scopes include the one an operation requires. */
+export declare function hasScope(granted: readonly ApiScope[], required: ApiScope): boolean;
+/** A random public key id (`key_…`), distinct from the secret and its hash. */
+export declare function generateKeyId(): string;
+/** Public projection of a stored key — never includes the hash/doc id. */
+export declare function toPublicApiKey(doc: ApiKeyDocument): PublicApiKey;
+export interface MintApiKeyInput {
+    orgId: string;
+    name: string;
+    scopes: readonly string[];
+    createdBy: string;
+    /** Optional absolute expiry, epoch ms. */
+    expiresAtMs?: number | null;
+}
+/**
+ * Create a key for an org. Returns the raw `token` (show once) and the public
+ * metadata. Invalid scopes are dropped; at least one valid scope is required.
+ */
+export declare function mintApiKey(input: MintApiKeyInput): Promise<{
+    token: string;
+    key: PublicApiKey;
+}>;
+/**
+ * Resolve a raw token to its org/scopes, or `null` if it is malformed,
+ * unknown, revoked, or expired. Refreshes `lastUsedAt` at most once a minute
+ * (fire-and-forget) to avoid a write on every request.
+ */
+export declare function verifyApiKey(token: string): Promise<VerifiedApiKey | null>;
+/** All keys for an org, newest first (metadata only). */
+export declare function listApiKeys(orgId: string): Promise<PublicApiKey[]>;
+/** Revoke a key by its public id. Returns false if not found/already revoked. */
+export declare function revokeApiKey(orgId: string, keyId: string): Promise<boolean>;