nuxt-observe 0.0.2

package/dist/runtime/server/utils/provisioning.js

@@ -0,0 +1,299 @@
+import { getRequestURL } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+import { slugify } from "../../shared/utils/slug.js";
+import { buildIngestUrl, buildFroggerSnippet } from "../../shared/utils/frogger-snippet.js";
+import { serviceScopeFilter } from "./authz.js";
+import {
+  createService,
+  getServiceById,
+  getServiceBySlug,
+  updateService,
+  softDeleteService,
+  restoreService,
+  getServiceAppNames,
+  setServiceAppNames,
+  setServiceAllowedOrigins,
+  getServiceAllowedOrigins,
+  SERVICE_DELETE_RETENTION_MS
+} from "./services.js";
+import {
+  createGroup,
+  getGroupById,
+  getGroupBySlug,
+  listGroups,
+  updateGroup as updateGroupRow,
+  deleteGroup as deleteGroupRow,
+  assignServiceToGroup,
+  listServicesInGroup
+} from "./groups.js";
+import { mintApiKey, rotateApiKey, revokeApiKey, listApiKeys } from "./api-keys.js";
+import * as dbUsers from "./db/users.js";
+import { useObserveDb } from "./db.js";
+export { SERVICE_DELETE_RETENTION_MS };
+function configServiceSlugs() {
+  const services = useRuntimeConfig().observe.services ?? [];
+  return new Set(services.map((s) => s.slug));
+}
+function toListItem(row, keyCount, configSlugs) {
+  return {
+    id: row.id,
+    slug: row.slug,
+    name: row.name,
+    type: row.type,
+    kind: row.kind,
+    env: row.env,
+    groupId: row.group_id,
+    versionTracking: !!row.version_tracking,
+    currentVersion: row.current_version,
+    keyCount,
+    managedByConfig: configSlugs.has(row.slug),
+    deletedAt: row.deleted_at,
+    purgeAt: row.deleted_at === null ? null : row.deleted_at + SERVICE_DELETE_RETENTION_MS
+  };
+}
+export async function listServicesForPrincipal(event, principal, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const scope = await serviceScopeFilter(event, principal, { column: "s.id", db });
+  const where = scope.clause ? `WHERE ${scope.clause}` : "";
+  const rows = await db.prepare(
+    `SELECT s.*, (SELECT COUNT(*) FROM api_keys k WHERE k.service_id = s.id AND k.revoked_at IS NULL) AS key_count
+       FROM services s
+       ${where}
+       ORDER BY (s.deleted_at IS NOT NULL), s.created_at`
+  ).all(...scope.params);
+  const configSlugs = configServiceSlugs();
+  return rows.map((r) => toListItem(r, r.key_count, configSlugs));
+}
+async function keyCountFor(serviceId, db) {
+  const row = await db.prepare("SELECT COUNT(*) AS c FROM api_keys WHERE service_id = ? AND revoked_at IS NULL").get(serviceId);
+  return row.c;
+}
+export async function getServiceDetail(id, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const row = await getServiceById(id, { db });
+  if (!row) return null;
+  const [appNames, allowedOrigins, keyCount] = await Promise.all([
+    getServiceAppNames(id, { db }),
+    getServiceAllowedOrigins(id, { db }),
+    keyCountFor(id, db)
+  ]);
+  let group = null;
+  if (row.group_id) {
+    const g = await getGroupById(row.group_id, { db });
+    if (g) group = { id: g.id, slug: g.slug, name: g.name };
+  }
+  const base = toListItem(row, keyCount, configServiceSlugs());
+  return { ...base, appNames, allowedOrigins, group };
+}
+async function uniqueSlug(name, db) {
+  const base = slugify(name);
+  let candidate = base;
+  let n = 2;
+  while (await getServiceBySlug(candidate, { db })) {
+    candidate = `${base}-${n++}`;
+  }
+  return candidate;
+}
+export async function createServiceFromInput(input, principal, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const slug = await uniqueSlug(input.name, db);
+  const svc = await createService({
+    slug,
+    name: input.name,
+    type: input.type,
+    kind: input.kind,
+    env: input.env,
+    versionTracking: input.versionTracking,
+    createdBy: principal.sub
+  }, { db });
+  await setServiceAppNames(svc.id, input.appNames, { db });
+  if (input.kind === "browser" && input.allowedOrigins.length) {
+    await setServiceAllowedOrigins(svc.id, input.allowedOrigins, { db });
+  }
+  return await getServiceDetail(svc.id, { db });
+}
+export async function updateServiceFromInput(id, patch, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const existing = await getServiceById(id, { db });
+  if (!existing) return null;
+  const scalarPatch = {};
+  if (patch.name !== void 0) scalarPatch.name = patch.name;
+  if (patch.type !== void 0) scalarPatch.type = patch.type;
+  if (patch.kind !== void 0) scalarPatch.kind = patch.kind;
+  if ("env" in patch) scalarPatch.env = patch.env ?? null;
+  if ("groupId" in patch) scalarPatch.groupId = patch.groupId ?? null;
+  if (patch.versionTracking !== void 0) scalarPatch.versionTracking = patch.versionTracking;
+  if ("currentVersion" in patch) scalarPatch.currentVersion = patch.currentVersion ?? null;
+  if (Object.keys(scalarPatch).length) await updateService(id, scalarPatch, { db });
+  if (patch.appNames !== void 0) await setServiceAppNames(id, patch.appNames, { db });
+  const effectiveKind = patch.kind ?? existing.kind;
+  if (effectiveKind === "server") {
+    if (existing.kind === "browser" || patch.allowedOrigins !== void 0) {
+      await setServiceAllowedOrigins(id, [], { db });
+    }
+  } else if (patch.allowedOrigins !== void 0) {
+    await setServiceAllowedOrigins(id, patch.allowedOrigins, { db });
+  }
+  return await getServiceDetail(id, { db });
+}
+export async function softDeleteServiceById(id, ctx = {}) {
+  const deletedAt = await softDeleteService(id, ctx);
+  if (deletedAt === null) return null;
+  return { deletedAt, purgeAt: deletedAt + SERVICE_DELETE_RETENTION_MS };
+}
+export async function restoreServiceById(id, ctx = {}) {
+  const row = await restoreService(id, ctx);
+  if (!row) return null;
+  return await getServiceDetail(id, ctx);
+}
+function resolveIngestOrigin(event) {
+  const override = useRuntimeConfig().public.observe.ingestBaseUrl;
+  if (override) return override;
+  return getRequestURL(event, { xForwardedHost: true, xForwardedProto: true }).origin;
+}
+function toMintedKey(event, raw, prefix) {
+  const origin = resolveIngestOrigin(event);
+  return {
+    key: raw,
+    prefix,
+    ingestUrl: buildIngestUrl(origin, raw),
+    snippet: buildFroggerSnippet({ origin, key: raw })
+  };
+}
+export async function listKeyMeta(serviceId, ctx = {}) {
+  const rows = await listApiKeys(serviceId, ctx);
+  return rows.map((r) => ({
+    id: r.id,
+    keyPrefix: r.key_prefix,
+    label: r.label,
+    createdAt: r.created_at,
+    revokedAt: r.revoked_at,
+    lastUsedAt: r.last_used_at
+  }));
+}
+export async function mintKey(event, serviceId, label, ctx = {}) {
+  const { raw, prefix } = await mintApiKey(serviceId, label, ctx);
+  return toMintedKey(event, raw, prefix);
+}
+export async function rotateKey(event, serviceId, oldKeyId, label, ctx = {}) {
+  const { raw, prefix } = await rotateApiKey(oldKeyId, serviceId, label, ctx);
+  return toMintedKey(event, raw, prefix);
+}
+export async function revokeKey(keyId, ctx = {}) {
+  await revokeApiKey(keyId, ctx);
+}
+export async function keyBelongsToService(keyId, serviceId, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const row = await db.prepare("SELECT 1 AS ok FROM api_keys WHERE id = ? AND service_id = ?").get(keyId, serviceId);
+  return !!row;
+}
+function toGroupListItem(group, serviceCount) {
+  return { id: group.id, slug: group.slug, name: group.name, serviceCount };
+}
+export async function listGroupsForPrincipal(event, principal, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const scope = await serviceScopeFilter(event, principal, { column: "id", db });
+  const groups = await listGroups({ db });
+  const out = [];
+  for (const g of groups) {
+    const clause = scope.clause ? ` AND ${scope.clause}` : "";
+    const row = await db.prepare(
+      `SELECT COUNT(*) AS c FROM services WHERE group_id = ? AND deleted_at IS NULL${clause}`
+    ).get(g.id, ...scope.params);
+    if (scope.clause && row.c === 0) continue;
+    out.push(toGroupListItem(g, row.c));
+  }
+  return out;
+}
+export async function createGroupFromInput(name, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const base = slugify(name);
+  let slug = base;
+  let n = 2;
+  while (await getGroupBySlug(slug, { db })) slug = `${base}-${n++}`;
+  const group = await createGroup({ slug, name }, { db });
+  return { ok: true, group };
+}
+export async function updateGroupById(id, name, ctx = {}) {
+  return await updateGroupRow(id, { name }, ctx);
+}
+export async function deleteGroupById(id, ctx = {}) {
+  return await deleteGroupRow(id, ctx);
+}
+export async function setGroupMembership(groupId, serviceIds, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const target = new Set(serviceIds);
+  const current = await listServicesInGroup(groupId, { db });
+  const currentIds = new Set(current.map((s) => s.id));
+  await db.sql`BEGIN`;
+  try {
+    for (const svc of current) {
+      if (!target.has(svc.id)) await assignServiceToGroup(svc.id, null, { db });
+    }
+    for (const id of target) {
+      if (!currentIds.has(id)) await assignServiceToGroup(id, groupId, { db });
+    }
+    await db.sql`COMMIT`;
+  } catch (e) {
+    await db.sql`ROLLBACK`;
+    throw e;
+  }
+}
+export async function getGroupDetail(id, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const group = await getGroupById(id, { db });
+  if (!group) return null;
+  const services = await listServicesInGroup(id, { db });
+  const configSlugs = configServiceSlugs();
+  const items = await Promise.all(services.map(async (s) => toListItem(s, await keyCountFor(s.id, db), configSlugs)));
+  return { group, services: items };
+}
+export function listUsers() {
+  const users = useRuntimeConfig().observe.auth?.users ?? [];
+  return users.map((u) => ({
+    id: u.name,
+    name: u.name,
+    role: u.role,
+    assignment: u.role === "admin" ? { services: ["*"], groups: ["*"] } : { services: u.assignedServices ?? [], groups: u.assignedGroups ?? [] }
+  }));
+}
+export function isDbProviderActive() {
+  return useRuntimeConfig().observe.auth?.provider === "db";
+}
+export async function listDbUsers(ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const rows = await dbUsers.listUsers({ db });
+  const out = [];
+  for (const row of rows) {
+    const assignment = row.role === "admin" ? { services: ["*"], groups: ["*"] } : await dbUsers.getUserAssignments(row.id, { db });
+    out.push({ id: row.id, name: row.display_name ?? row.username, role: row.role, assignment });
+  }
+  return out;
+}
+function toUserDetail(row, assignment, rows) {
+  return {
+    id: row.id,
+    username: row.username,
+    displayName: row.display_name,
+    name: row.display_name ?? row.username,
+    role: row.role,
+    disabled: !!row.disabled,
+    source: row.source,
+    hasPassword: row.password_hash !== null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    assignment,
+    services: rows.services,
+    groups: rows.groups
+  };
+}
+export async function getUserDetail(id, ctx = {}) {
+  const db = ctx.db ?? useObserveDb();
+  const row = await dbUsers.getUserById(id, { db });
+  if (!row) return null;
+  const [assignment, rows] = await Promise.all([
+    dbUsers.getUserAssignments(id, { db }),
+    dbUsers.getUserAssignmentRows(id, { db })
+  ]);
+  return toUserDetail(row, assignment, rows);
+}

package/dist/runtime/server/utils/rate-limit.d.ts

@@ -0,0 +1,11 @@
+/**
+ * In-memory per-service token bucket. Returns false (-> handler throws 429) when
+ * over limit. Effectively off unless observe.ingest.rateLimit.perServicePerMinute
+ * is a positive number. Single-process only; a multi-instance deploy under-counts
+ * and would need a shared store (documented limitation).
+ *
+ * `now` is injectable so refill behavior is testable without wall-clock waits.
+ */
+export declare function checkIngestRateLimit(serviceId: string, now?: number): boolean;
+/** Clears all buckets. Test-only, so one test's fills don't leak into the next. */
+export declare function __resetRateLimitForTests(): void;

package/dist/runtime/server/utils/rate-limit.js

@@ -0,0 +1,22 @@
+import { useRuntimeConfig } from "nitropack/runtime";
+const buckets = /* @__PURE__ */ new Map();
+export function checkIngestRateLimit(serviceId, now = Date.now()) {
+  const rl = useRuntimeConfig().observe?.ingest?.rateLimit;
+  const perMin = rl?.perServicePerMinute;
+  if (!perMin || perMin <= 0) return true;
+  const burst = rl?.burst ?? perMin;
+  const ratePerMs = perMin / 6e4;
+  let b = buckets.get(serviceId);
+  if (!b) {
+    b = { tokens: burst, updated: now };
+    buckets.set(serviceId, b);
+  }
+  b.tokens = Math.min(burst, b.tokens + (now - b.updated) * ratePerMs);
+  b.updated = now;
+  if (b.tokens < 1) return false;
+  b.tokens -= 1;
+  return true;
+}
+export function __resetRateLimitForTests() {
+  buckets.clear();
+}

package/dist/runtime/server/utils/require-observe-session.d.ts

@@ -0,0 +1,15 @@
+import type { H3Event } from 'h3';
+import type { Principal } from '../../shared/auth/types.js';
+/**
+ * The single util every protected /api/observe/* route calls. Resolves the cookie session
+ * first (nuxt-auth-utils; requireUserSession throws 401 when absent), then falls back to a
+ * stateless `Authorization: Bearer <token>` verified by the JWT provider when
+ * `observe.auth.jwt.enabled` (CP16). The Bearer path NEVER mints a session cookie: it is
+ * stateless per request. When neither resolves, it throws the same 401 as before, so
+ * cookie-only clients are unaffected. This is the single permitted call-site change;
+ * requireCapability and every route above it stay untouched.
+ *
+ * session.user is already Principal once the #auth-utils augmentation (types/session.d.ts)
+ * is in the server tsconfig; the cast is belt-and-braces for build orders where it is not.
+ */
+export declare function requireObserveSession(event: H3Event): Promise<Principal>;

package/dist/runtime/server/utils/require-observe-session.js

@@ -0,0 +1,25 @@
+import { createError, getHeader } from "h3";
+import { requireUserSession } from "#imports";
+import { getJwtAuthProvider } from "../auth/provider.js";
+export async function requireObserveSession(event) {
+  try {
+    const session = await requireUserSession(event);
+    return session.user;
+  } catch {
+    const token = bearerToken(event);
+    if (token) {
+      const jwt = getJwtAuthProvider();
+      if (jwt) {
+        const res = await jwt.authenticate({ token }, event);
+        if (res.ok && res.principal) return res.principal;
+      }
+    }
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+}
+function bearerToken(event) {
+  const header = getHeader(event, "authorization");
+  if (!header) return null;
+  const match = /^Bearer\s+(\S.*)$/i.exec(header.trim());
+  return match ? match[1] : null;
+}

package/dist/runtime/server/utils/rollout.d.ts

@@ -0,0 +1,19 @@
+import { type VersionStat, type VersionCompare } from '../../shared/schema/rollout.js';
+import { type Database } from './db.js';
+/**
+ * CP13 rollout aggregates. Same contract as getStats (CP8): both builders take a
+ * RESOLVED scope (string[] | '*'), not an event — the handler runs requireCapability /
+ * getAllowedServiceIds / resolveEffectiveScope first — so these stay pure and
+ * node-testable via `opts.db`. Scope is applied as `service_id IN (...)`: '*' = no
+ * restriction; an empty list short-circuits before touching the db (a "sees nothing"
+ * scope must never become an unscoped query). NULL version folds under '(unversioned)'
+ * via COALESCE so it never fragments or vanishes from the GROUP BY. Error = level 0,
+ * identical to CP8's stats query.
+ */
+interface QueryOpts {
+    env?: string;
+    db?: Database;
+}
+export declare function getVersionSummary(scope: string[] | '*', from: number, to: number, opts?: QueryOpts): Promise<VersionStat[]>;
+export declare function getVersionSeries(scope: string[] | '*', from: number, to: number, bucketMs: number, opts?: QueryOpts): Promise<VersionCompare>;
+export {};

package/dist/runtime/server/utils/rollout.js

@@ -0,0 +1,56 @@
+import {
+  pivotVersionSeries,
+  UNVERSIONED
+} from "../../shared/schema/rollout.js";
+import { useObserveDb } from "./db.js";
+function scopeClause(scope) {
+  return scope === "*" ? { clause: "", params: [] } : { clause: `AND service_id IN (${scope.map(() => "?").join(",")})`, params: [...scope] };
+}
+export async function getVersionSummary(scope, from, to, opts = {}) {
+  if (scope !== "*" && scope.length === 0) return [];
+  const db = opts.db ?? useObserveDb();
+  const scoped = scopeClause(scope);
+  const envClause = opts.env != null ? "AND env = ?" : "";
+  const envParams = opts.env != null ? [opts.env] : [];
+  const params = [from, to, ...scoped.params, ...envParams];
+  const rows = await db.prepare(
+    `SELECT COALESCE(version, '${UNVERSIONED}') AS version,
+            COUNT(*) AS total,
+            SUM(level = 0) AS errors,
+            MIN(time) AS firstSeen, MAX(time) AS lastSeen
+     FROM logs
+     WHERE time >= ? AND time <= ? ${scoped.clause} ${envClause}
+     GROUP BY COALESCE(version, '${UNVERSIONED}')
+     ORDER BY lastSeen DESC`
+  ).all(...params);
+  return rows.map((r) => {
+    const errors = r.errors ?? 0;
+    return {
+      version: r.version,
+      total: r.total,
+      errors,
+      errorRate: r.total ? errors / r.total : 0,
+      firstSeen: r.firstSeen,
+      lastSeen: r.lastSeen
+    };
+  });
+}
+export async function getVersionSeries(scope, from, to, bucketMs, opts = {}) {
+  if (scope !== "*" && scope.length === 0) return pivotVersionSeries([], from, to, bucketMs);
+  const db = opts.db ?? useObserveDb();
+  const scoped = scopeClause(scope);
+  const envClause = opts.env != null ? "AND env = ?" : "";
+  const envParams = opts.env != null ? [opts.env] : [];
+  const params = [bucketMs, from, to, ...scoped.params, ...envParams];
+  const rows = await db.prepare(
+    `SELECT CAST(time / ? AS INTEGER) AS b,
+            COALESCE(version, '${UNVERSIONED}') AS version,
+            COUNT(*) AS total,
+            SUM(level = 0) AS errors
+     FROM logs
+     WHERE time >= ? AND time <= ? ${scoped.clause} ${envClause}
+     GROUP BY b, COALESCE(version, '${UNVERSIONED}')
+     ORDER BY b`
+  ).all(...params);
+  return pivotVersionSeries(rows, from, to, bucketMs);
+}

package/dist/runtime/server/utils/scope.d.ts

@@ -0,0 +1,14 @@
+import type { H3Event } from 'h3';
+import type { Principal } from '../../shared/auth/types.js';
+/**
+ * Narrow the caller's allowed scope by an optional ?service/?group slug. Follows the
+ * CP6 invariant: a plain scoped read never 403s (it just returns fewer rows); 403 is
+ * minted only when the caller NAMES a resource outside its scope. Unknown slugs 404.
+ * An admin naming a service/group still gets concrete ids back, so the response is
+ * filtered to what was asked. When both are given, the narrower ?service wins.
+ * Shared by the overview (CP7), stats (CP8), logs (CP9), and activity (CP10) endpoints.
+ */
+export declare function resolveEffectiveScope(event: H3Event, principal: Principal, allowed: string[] | '*', filter: {
+    service?: string;
+    group?: string;
+}): Promise<string[] | '*'>;

package/dist/runtime/server/utils/scope.js

@@ -0,0 +1,28 @@
+import { createError } from "h3";
+import { assertServiceInScope } from "./authz.js";
+import { getServiceBySlug } from "./services.js";
+import { getGroupBySlug, listServicesInGroup } from "./groups.js";
+export async function resolveEffectiveScope(event, principal, allowed, filter) {
+  if (filter.service) {
+    const svc = await getServiceBySlug(filter.service);
+    if (!svc) {
+      throw createError({ statusCode: 404, statusMessage: "Not Found", data: { error: "UNKNOWN_SERVICE", service: filter.service } });
+    }
+    await assertServiceInScope(event, principal, svc.id);
+    return [svc.id];
+  }
+  if (filter.group) {
+    const group = await getGroupBySlug(filter.group);
+    if (!group) {
+      throw createError({ statusCode: 404, statusMessage: "Not Found", data: { error: "UNKNOWN_GROUP", group: filter.group } });
+    }
+    const memberIds = (await listServicesInGroup(group.id)).map((s) => s.id);
+    if (allowed === "*") return memberIds;
+    const intersection = memberIds.filter((id) => allowed.includes(id));
+    if (intersection.length === 0) {
+      throw createError({ statusCode: 403, statusMessage: "Forbidden", data: { error: "OUT_OF_SCOPE", group: filter.group } });
+    }
+    return intersection;
+  }
+  return allowed;
+}

package/dist/runtime/server/utils/seed.d.ts

@@ -0,0 +1,18 @@
+import { type ObserveSeedConfig } from '../../shared/schema/registry.js';
+import { type Database } from './db.js';
+/**
+ * Upsert the config-declared registry into the DB, in one transaction, in
+ * dependency order: groups -> services (+ app_names) -> api keys. Fully
+ * idempotent: a second run with the same config yields identical row counts.
+ *
+ * User rows are intentionally NOT written here: phase-1 auth (CP5) authenticates
+ * config-seeded users from runtimeConfig (observe.auth.users). The `users` tables
+ * stay empty until an admin creates real accounts in CP16, at which point the
+ * config admin becomes a gated bootstrap fallback (see shared/auth/roles.ts).
+ *
+ * All SQL is inlined here rather than via the create/set helpers so the whole
+ * seed runs inside a single BEGIN (nested BEGINs are rejected by sqlite).
+ */
+export declare function seedObserveRegistry(config: ObserveSeedConfig | undefined, opts?: {
+    db?: Database;
+}): Promise<void>;

package/dist/runtime/server/utils/seed.js

@@ -0,0 +1,70 @@
+import { uuidv7 } from "../../shared/utils/uuid.js";
+import { zObserveSeedConfig } from "../../shared/schema/registry.js";
+import { hashApiKey } from "./api-keys.js";
+import { useObserveDb } from "./db.js";
+export async function seedObserveRegistry(config, opts = {}) {
+  if (!config) return;
+  const parsed = zObserveSeedConfig.parse(config);
+  const db = opts.db ?? useObserveDb();
+  await db.sql`BEGIN`;
+  try {
+    const now = Date.now();
+    for (const g of parsed.groups ?? []) {
+      const existing = await db.prepare("SELECT id FROM groups WHERE slug = ?").get(g.slug);
+      if (existing) {
+        await db.sql`UPDATE groups SET name = ${g.name}, updated_at = ${now} WHERE slug = ${g.slug}`;
+      } else {
+        await db.sql`INSERT INTO groups (id, slug, name, created_at, updated_at) VALUES (${uuidv7()}, ${g.slug}, ${g.name}, ${now}, ${now})`;
+      }
+    }
+    for (const s of parsed.services ?? []) {
+      let groupId = null;
+      if (s.group) {
+        const grp = await db.prepare("SELECT id FROM groups WHERE slug = ?").get(s.group);
+        groupId = grp?.id ?? null;
+      }
+      const vt = s.versionTracking ? 1 : 0;
+      let serviceId;
+      const existing = await db.prepare("SELECT id FROM services WHERE slug = ?").get(s.slug);
+      if (existing) {
+        serviceId = existing.id;
+        await db.sql`
+          UPDATE services
+          SET name = ${s.name}, group_id = ${groupId}, env = ${s.env ?? null},
+              version_tracking = ${vt}, current_version = ${s.currentVersion ?? null}, kind = ${s.kind}, type = ${s.type},
+              deleted_at = NULL, updated_at = ${now}
+          WHERE id = ${serviceId}
+        `;
+      } else {
+        serviceId = uuidv7();
+        await db.sql`
+          INSERT INTO services (id, slug, name, group_id, env, version_tracking, current_version, kind, type, created_by, created_at, updated_at)
+          VALUES (${serviceId}, ${s.slug}, ${s.name}, ${groupId}, ${s.env ?? null}, ${vt}, ${s.currentVersion ?? null}, ${s.kind}, ${s.type}, ${"config"}, ${now}, ${now})
+        `;
+      }
+      await db.sql`DELETE FROM service_app_names WHERE service_id = ${serviceId}`;
+      for (const appName of s.appNames ?? []) {
+        await db.sql`INSERT INTO service_app_names (service_id, app_name) VALUES (${serviceId}, ${appName})`;
+      }
+      await db.sql`DELETE FROM service_allowed_origins WHERE service_id = ${serviceId}`;
+      for (const origin of [...new Set(s.allowedOrigins ?? [])]) {
+        await db.sql`INSERT INTO service_allowed_origins (service_id, origin) VALUES (${serviceId}, ${origin})`;
+      }
+      if (s.key) {
+        const keyHash = hashApiKey(s.key);
+        const present = await db.prepare("SELECT id FROM api_keys WHERE key_hash = ?").get(keyHash);
+        if (!present) {
+          const prefix = s.key.slice(0, 11);
+          await db.sql`
+            INSERT INTO api_keys (id, service_id, key_hash, key_prefix, label, created_at)
+            VALUES (${uuidv7()}, ${serviceId}, ${keyHash}, ${prefix}, ${"seed"}, ${now})
+          `;
+        }
+      }
+    }
+    await db.sql`COMMIT`;
+  } catch (e) {
+    await db.sql`ROLLBACK`;
+    throw e;
+  }
+}

package/dist/runtime/server/utils/services.d.ts

@@ -0,0 +1,91 @@
+import type { ServiceType } from '../../shared/schema/provisioning.js';
+import { type Database } from './db.js';
+export interface ServiceRow {
+    id: string;
+    slug: string;
+    name: string;
+    group_id: string | null;
+    env: string | null;
+    version_tracking: number;
+    current_version: string | null;
+    kind: 'server' | 'browser';
+    type: ServiceType;
+    deleted_at: number | null;
+    created_by: string | null;
+    created_at: number;
+    updated_at: number;
+}
+interface DbOpts {
+    db?: Database;
+}
+/** Rollback window for a soft-deleted service before permanent purge. */
+export declare const SERVICE_DELETE_RETENTION_MS: number;
+export declare function createService(input: {
+    slug: string;
+    name: string;
+    groupId?: string | null;
+    env?: string;
+    versionTracking?: boolean;
+    currentVersion?: string;
+    kind?: 'server' | 'browser';
+    type?: ServiceType;
+    createdBy?: string;
+}, opts?: DbOpts): Promise<ServiceRow>;
+export declare function getServiceById(id: string, opts?: DbOpts): Promise<ServiceRow | null>;
+export declare function getServiceBySlug(slug: string, opts?: DbOpts): Promise<ServiceRow | null>;
+/** Active services by default; pass `includeDeleted` to also return soft-deleted rows. */
+export declare function listServices(opts?: DbOpts & {
+    includeDeleted?: boolean;
+}): Promise<ServiceRow[]>;
+export declare function updateService(id: string, patch: Partial<{
+    name: string;
+    groupId: string | null;
+    env: string | null;
+    versionTracking: boolean;
+    currentVersion: string | null;
+    kind: 'server' | 'browser';
+    type: ServiceType;
+}>, opts?: DbOpts): Promise<ServiceRow | null>;
+/**
+ * Mark a service for deletion (soft-delete). It disappears from the active list
+ * immediately but is recoverable via restoreService until the retention window
+ * elapses, at which point purgeExpiredServices removes it for good. Returns the
+ * epoch-ms `deletedAt` stamp (null if the service did not exist / was already gone).
+ */
+export declare function softDeleteService(id: string, opts?: DbOpts): Promise<number | null>;
+/** Clear the soft-delete marker, restoring a service to the active list. */
+export declare function restoreService(id: string, opts?: DbOpts): Promise<ServiceRow | null>;
+/**
+ * Hard-delete a single service and every child row (app_names, allowed_origins,
+ * api_keys). Unlike the pre-CP11 version this also cascades api_keys, so no orphan
+ * key can outlive its service. Used by the retention purge and by tests.
+ */
+export declare function deleteService(id: string, opts?: DbOpts): Promise<void>;
+/**
+ * Permanently remove every service whose soft-delete stamp is older than
+ * `retentionMs`. Called by the scheduled observe:purge task. Returns the count
+ * purged. Each service is removed with its full child cascade.
+ */
+export declare function purgeExpiredServices(retentionMs: number, opts?: DbOpts): Promise<{
+    purged: number;
+}>;
+/** Replace the full set of app names attributed to a service, in one transaction. */
+export declare function setServiceAppNames(serviceId: string, appNames: string[], opts?: DbOpts): Promise<void>;
+export declare function getServiceAppNames(serviceId: string, opts?: DbOpts): Promise<string[]>;
+export declare function resolveServiceByAppName(appName: string, opts?: DbOpts): Promise<ServiceRow | null>;
+export interface ServiceCorsMeta {
+    serviceId: string;
+    kind: 'server' | 'browser';
+    allowedOrigins: string[];
+}
+/** Replace the full browser origin allowlist for a service, deduped, in one transaction. */
+export declare function setServiceAllowedOrigins(serviceId: string, origins: string[], opts?: DbOpts): Promise<void>;
+export declare function getServiceAllowedOrigins(serviceId: string, opts?: DbOpts): Promise<string[]>;
+/**
+ * Non-throwing lookup used by the ingest CORS step BEFORE auth. Resolves a raw
+ * ?key= to its service's kind + browser origin allowlist. Returns null for an
+ * unknown/revoked key (-> no cross-origin grant, request still proceeds to auth).
+ * Does NOT bump last_used_at: a preflight is not an ingest.
+ */
+export declare function resolveServiceCorsMeta(rawKey: string | undefined, opts?: DbOpts): Promise<ServiceCorsMeta | null>;
+export {};