nuxt-observe 0.0.2

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

@@ -0,0 +1,142 @@
+import { uuidv7 } from "../../shared/utils/uuid.js";
+import { hashApiKey } from "./api-keys.js";
+import { useObserveDb } from "./db.js";
+export const SERVICE_DELETE_RETENTION_MS = 60 * 60 * 1e3;
+export async function createService(input, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const id = uuidv7();
+  const now = Date.now();
+  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 (
+      ${id}, ${input.slug}, ${input.name}, ${input.groupId ?? null}, ${input.env ?? null},
+      ${input.versionTracking ? 1 : 0}, ${input.currentVersion ?? null}, ${input.kind ?? "server"}, ${input.type ?? "service"}, ${input.createdBy ?? null}, ${now}, ${now}
+    )
+  `;
+  return await getServiceById(id, opts);
+}
+export async function getServiceById(id, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const row = await db.prepare("SELECT * FROM services WHERE id = ?").get(id);
+  return row ?? null;
+}
+export async function getServiceBySlug(slug, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const row = await db.prepare("SELECT * FROM services WHERE slug = ?").get(slug);
+  return row ?? null;
+}
+export async function listServices(opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const where = opts.includeDeleted ? "" : "WHERE deleted_at IS NULL";
+  return await db.prepare(`SELECT * FROM services ${where} ORDER BY created_at`).all();
+}
+export async function updateService(id, patch, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const existing = await getServiceById(id, opts);
+  if (!existing) return null;
+  const name = patch.name ?? existing.name;
+  const groupId = "groupId" in patch ? patch.groupId ?? null : existing.group_id;
+  const env = "env" in patch ? patch.env ?? null : existing.env;
+  const versionTracking = patch.versionTracking === void 0 ? existing.version_tracking : patch.versionTracking ? 1 : 0;
+  const currentVersion = "currentVersion" in patch ? patch.currentVersion ?? null : existing.current_version;
+  const kind = patch.kind ?? existing.kind;
+  const type = patch.type ?? existing.type;
+  await db.sql`
+    UPDATE services
+    SET name = ${name}, group_id = ${groupId}, env = ${env},
+        version_tracking = ${versionTracking}, current_version = ${currentVersion}, kind = ${kind}, type = ${type}, updated_at = ${Date.now()}
+    WHERE id = ${id}
+  `;
+  return await getServiceById(id, opts);
+}
+export async function softDeleteService(id, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const existing = await getServiceById(id, opts);
+  if (!existing || existing.deleted_at !== null) return existing?.deleted_at ?? null;
+  const now = Date.now();
+  await db.sql`UPDATE services SET deleted_at = ${now}, updated_at = ${now} WHERE id = ${id}`;
+  return now;
+}
+export async function restoreService(id, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const existing = await getServiceById(id, opts);
+  if (!existing) return null;
+  await db.sql`UPDATE services SET deleted_at = NULL, updated_at = ${Date.now()} WHERE id = ${id}`;
+  return await getServiceById(id, opts);
+}
+export async function deleteService(id, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  await db.sql`DELETE FROM service_app_names WHERE service_id = ${id}`;
+  await db.sql`DELETE FROM service_allowed_origins WHERE service_id = ${id}`;
+  await db.sql`DELETE FROM api_keys WHERE service_id = ${id}`;
+  await db.sql`DELETE FROM services WHERE id = ${id}`;
+}
+export async function purgeExpiredServices(retentionMs, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const cutoff = Date.now() - retentionMs;
+  const rows = await db.prepare(
+    "SELECT id FROM services WHERE deleted_at IS NOT NULL AND deleted_at < ?"
+  ).all(cutoff);
+  for (const { id } of rows) {
+    await deleteService(id, opts);
+  }
+  return { purged: rows.length };
+}
+export async function setServiceAppNames(serviceId, appNames, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  await db.sql`BEGIN`;
+  try {
+    await db.sql`DELETE FROM service_app_names WHERE service_id = ${serviceId}`;
+    for (const appName of appNames) {
+      await db.sql`INSERT INTO service_app_names (service_id, app_name) VALUES (${serviceId}, ${appName})`;
+    }
+    await db.sql`COMMIT`;
+  } catch (e) {
+    await db.sql`ROLLBACK`;
+    throw e;
+  }
+}
+export async function getServiceAppNames(serviceId, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const rows = await db.prepare("SELECT app_name FROM service_app_names WHERE service_id = ? ORDER BY app_name").all(serviceId);
+  return rows.map((r) => r.app_name);
+}
+export async function resolveServiceByAppName(appName, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const row = await db.prepare(
+    "SELECT s.* FROM services s JOIN service_app_names a ON a.service_id = s.id WHERE a.app_name = ?"
+  ).get(appName);
+  return row ?? null;
+}
+export async function setServiceAllowedOrigins(serviceId, origins, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const unique = [...new Set(origins)];
+  await db.sql`BEGIN`;
+  try {
+    await db.sql`DELETE FROM service_allowed_origins WHERE service_id = ${serviceId}`;
+    for (const origin of unique) {
+      await db.sql`INSERT INTO service_allowed_origins (service_id, origin) VALUES (${serviceId}, ${origin})`;
+    }
+    await db.sql`COMMIT`;
+  } catch (e) {
+    await db.sql`ROLLBACK`;
+    throw e;
+  }
+}
+export async function getServiceAllowedOrigins(serviceId, opts = {}) {
+  const db = opts.db ?? useObserveDb();
+  const rows = await db.prepare("SELECT origin FROM service_allowed_origins WHERE service_id = ?").all(serviceId);
+  return rows.map((r) => r.origin);
+}
+export async function resolveServiceCorsMeta(rawKey, opts = {}) {
+  if (!rawKey) return null;
+  const db = opts.db ?? useObserveDb();
+  const svc = await db.prepare(
+    `SELECT s.id AS service_id, s.kind AS kind
+       FROM api_keys k JOIN services s ON s.id = k.service_id
+      WHERE k.key_hash = ? AND k.revoked_at IS NULL`
+  ).get(hashApiKey(rawKey));
+  if (!svc) return null;
+  const origins = await getServiceAllowedOrigins(svc.service_id, { db });
+  return { serviceId: svc.service_id, kind: svc.kind === "browser" ? "browser" : "server", allowedOrigins: origins };
+}

package/dist/runtime/server/utils/stats-query.d.ts

@@ -0,0 +1,40 @@
+import type { StatsBucket, StatsData, StatsSeriesMeta } from '../../shared/schema/stats.js';
+import type { Period } from '../../shared/utils/period.js';
+import { type Database } from './db.js';
+/**
+ * CP8 bucketed aggregates behind GET /api/observe/stats. Same contract as the CP7
+ * getOverview helper: takes a RESOLVED scope (string[] | '*'), not an event — the
+ * handler runs requireCapability/getAllowedServiceIds/resolveEffectiveScope first —
+ * so this stays pure and node-testable via `opts.db`.
+ *
+ * Bucketing is `CAST(time / ?bucketMs AS INTEGER)`: better-sqlite3 binds JS numbers
+ * as REAL, so a bound divisor does float division (a literal would int-divide); the
+ * CAST truncates toward zero, which equals floor for positive ms epochs, and keeps
+ * every value a bound parameter. GROUP BY on that index aggregates per window slice
+ * in SQL. The window is always time-bounded, riding idx_logs_service_time when
+ * scoped and idx_logs_time for admin. CP13 (rollout charts) reuses zeroFilledBuckets
+ * + the same GROUP BY shape with `version` as a second dimension.
+ */
+interface DbOpts {
+    db?: Database;
+}
+export interface StatsFilters {
+    version?: string;
+    level?: number;
+}
+/** Per-period default bucket size, targeting <= ~200 points per window. */
+export declare const DEFAULT_BUCKET_MS: Record<Period, number>;
+/** Hard ceiling on buckets per response; an explicit ?bucketMs below it is a 400. */
+export declare const MAX_BUCKETS = 500;
+/** Top-N services kept as distinct breakdown series; the tail folds into 'other'. */
+export declare const TOP_SERVICES = 8;
+export declare const OTHER_SERIES: StatsSeriesMeta;
+/**
+ * Contiguous zero-filled skeleton covering [from, to]: one bucket per integer index
+ * floor(time / bucketMs), ascending. Exported for CP13's rollout bucketing.
+ */
+export declare function zeroFilledBuckets(from: number, to: number, bucketMs: number): StatsBucket[];
+/** Zeroed response slice for an empty scope; never touches the db. */
+export declare function emptyStats(from: number, to: number, bucketMs: number): StatsData;
+export declare function getStats(scope: string[] | '*', from: number, to: number, bucketMs: number, filters?: StatsFilters, opts?: DbOpts): Promise<StatsData>;
+export {};

package/dist/runtime/server/utils/stats-query.js

@@ -0,0 +1,104 @@
+import { useObserveDb } from "./db.js";
+export const DEFAULT_BUCKET_MS = {
+  "15m": 15e3,
+  // 60 buckets
+  "1h": 6e4,
+  // 60 buckets
+  "24h": 9e5,
+  // 96 buckets
+  "7d": 36e5,
+  // 168 buckets
+  "30d": 216e5
+  // 120 buckets
+};
+export const MAX_BUCKETS = 500;
+export const TOP_SERVICES = 8;
+export const OTHER_SERIES = { id: "other", slug: "other", name: "Other" };
+export function zeroFilledBuckets(from, to, bucketMs) {
+  const bFrom = Math.floor(from / bucketMs);
+  const bTo = Math.floor(to / bucketMs);
+  const buckets = [];
+  for (let idx = bFrom; idx <= bTo; idx++) {
+    buckets.push({ t: idx * bucketMs, count: 0, errorCount: 0, warnCount: 0, byService: {} });
+  }
+  return buckets;
+}
+export function emptyStats(from, to, bucketMs) {
+  return {
+    buckets: zeroFilledBuckets(from, to, bucketMs),
+    services: [],
+    totals: { count: 0, errorCount: 0, warnCount: 0, errorRatePct: 0 }
+  };
+}
+export async function getStats(scope, from, to, bucketMs, filters = {}, opts = {}) {
+  if (scope !== "*" && scope.length === 0) return emptyStats(from, to, bucketMs);
+  const db = opts.db ?? useObserveDb();
+  const scoped = scope === "*" ? { clause: "", params: [] } : { clause: `AND service_id IN (${scope.map(() => "?").join(",")})`, params: [...scope] };
+  const filt = [];
+  const filtParams = [];
+  if (filters.version != null) {
+    filt.push("AND version = ?");
+    filtParams.push(filters.version);
+  }
+  if (filters.level != null) {
+    filt.push("AND level = ?");
+    filtParams.push(filters.level);
+  }
+  const where = `WHERE time >= ? AND time <= ? ${scoped.clause} ${filt.join(" ")}`;
+  const params = [bucketMs, from, to, ...scoped.params, ...filtParams];
+  const totalsRows = await db.prepare(
+    `SELECT CAST(time / ? AS INTEGER) AS b,
+            COUNT(*) AS count,
+            SUM(level = 0) AS errorCount,
+            SUM(level = 1) AS warnCount
+     FROM logs ${where}
+     GROUP BY b
+     ORDER BY b`
+  ).all(...params);
+  const breakdownRows = await db.prepare(
+    `SELECT CAST(time / ? AS INTEGER) AS b, service_id AS sid, COUNT(*) AS count
+     FROM logs ${where}
+     GROUP BY b, sid
+     ORDER BY b`
+  ).all(...params);
+  const buckets = zeroFilledBuckets(from, to, bucketMs);
+  const bFrom = Math.floor(from / bucketMs);
+  const bucketAt = (b) => buckets[b - bFrom];
+  for (const row of totalsRows) {
+    const bucket = bucketAt(row.b);
+    if (!bucket) continue;
+    bucket.count += row.count;
+    bucket.errorCount += row.errorCount ?? 0;
+    bucket.warnCount += row.warnCount ?? 0;
+  }
+  const totalBySid = /* @__PURE__ */ new Map();
+  for (const row of breakdownRows) {
+    if (!row.sid) continue;
+    totalBySid.set(row.sid, (totalBySid.get(row.sid) ?? 0) + row.count);
+  }
+  const byVolume = [...totalBySid.entries()].sort((a, b) => b[1] - a[1]);
+  const topIds = new Set(byVolume.slice(0, TOP_SERVICES).map(([id]) => id));
+  const folded = byVolume.length > TOP_SERVICES;
+  for (const row of breakdownRows) {
+    if (!row.sid) continue;
+    const bucket = bucketAt(row.b);
+    if (!bucket) continue;
+    const key = topIds.has(row.sid) ? row.sid : OTHER_SERIES.id;
+    bucket.byService[key] = (bucket.byService[key] ?? 0) + row.count;
+  }
+  const ids = [...topIds];
+  const metaRows = ids.length ? await db.prepare(
+    `SELECT id, slug, name FROM services WHERE id IN (${ids.map(() => "?").join(",")})`
+  ).all(...ids) : [];
+  const meta = new Map(metaRows.map((r) => [r.id, r]));
+  const services = byVolume.slice(0, TOP_SERVICES).map(([id]) => meta.get(id) ?? { id, slug: id, name: id });
+  if (folded) services.push({ ...OTHER_SERIES });
+  const totals = { count: 0, errorCount: 0, warnCount: 0, errorRatePct: 0 };
+  for (const bucket of buckets) {
+    totals.count += bucket.count;
+    totals.errorCount += bucket.errorCount;
+    totals.warnCount += bucket.warnCount;
+  }
+  totals.errorRatePct = totals.count ? totals.errorCount / totals.count * 100 : 0;
+  return { buckets, services, totals };
+}

package/dist/runtime/shared/auth/roles.d.ts

@@ -0,0 +1,34 @@
+import type { Role } from './types.js';
+export declare const ROLES: readonly ["admin", "manager", "viewer"];
+/** Assignment sentinel: every service / every group. Admins carry this. */
+export declare const ALL: "*";
+/** Higher = more privilege. CP6 compares ranks for role-gated capabilities. */
+export declare const ROLE_RANK: Record<Role, number>;
+export declare function isRole(x: unknown): x is Role;
+/**
+ * CAPABILITY MATRIX — DOCUMENTED FOR CP6, NOT ENFORCED IN CP5.
+ * CP5 gates routes only with requireUserSession (logged-in vs not). CP6 implements
+ * these checks in the AuthorizationStore / route guards, scoped by Assignment.
+ *
+ *  capability                     | admin | manager        | viewer
+ *  -------------------------------|-------|----------------|----------------
+ *  view logs / dashboards         |  all  | assigned only  | assigned only
+ *  manage services (create/edit)  |  yes  | assigned only  | no
+ *  manage groups                  |  yes  | no             | no
+ *  mint / revoke api keys         |  yes  | assigned only  | no
+ *  manage users + assignments     |  yes  | no             | no  (CP16 UI)
+ *  change retention / settings    |  yes  | no             | no
+ *
+ * Scoping rule CP6 consumes: a principal may act on service slug S iff
+ *   assignment.services includes '*' OR S, OR S belongs to a group in assignment.groups.
+ * Admin's assignment is { services:['*'], groups:['*'] }, so every check short-circuits true.
+ *
+ * BOOTSTRAP-ADMIN LIFECYCLE (unified across phases — see CP5-HANDOFF §2 / PLAN CP16):
+ *   Phase 1 (CP5, config provider): observe.auth.users is the whole user set. At least
+ *     one admin is the bootstrap admin; you deploy with it and log in.
+ *   Phase 2 (CP16, db provider): the `users` table is authoritative. The config bootstrap
+ *     admin is honoured ONLY as a fallback while the DB has zero admin users. Creating a
+ *     real DB admin closes the window automatically ("admin admin no longer needed"); the
+ *     config admin is never written to the DB. Deleting every DB admin reopens it (recovery
+ *     hatch). CP16 reuses this file's config-provider logic for that gated fallback.
+ */

package/dist/runtime/shared/auth/roles.js

@@ -0,0 +1,6 @@
+export const ROLES = ["admin", "manager", "viewer"];
+export const ALL = "*";
+export const ROLE_RANK = { admin: 3, manager: 2, viewer: 1 };
+export function isRole(x) {
+  return typeof x === "string" && ROLES.includes(x);
+}

package/dist/runtime/shared/auth/schema.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+/**
+ * Pure zod + local only, mirroring the registry schema rule: this file must never
+ * import #imports, node:crypto, or any server util so it stays node-unit-testable
+ * and app-importable.
+ */
+export declare const roleSchema: z.ZodEnum<{
+    admin: "admin";
+    manager: "manager";
+    viewer: "viewer";
+}>;
+export declare const assignmentSchema: z.ZodObject<{
+    services: z.ZodArray<z.ZodString>;
+    groups: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Build-time validation of a seeded user (observe.auth.users). At least one of
+ * passwordHash / passwordEnv is required — a user with neither can never authenticate.
+ * Plaintext passwords are NOT accepted in config: only a pre-computed scrypt hash, or
+ * the NAME of an env var holding the plaintext/hash, resolved at authenticate time.
+ */
+export declare const observeUserSchema: z.ZodObject<{
+    name: z.ZodString;
+    role: z.ZodEnum<{
+        admin: "admin";
+        manager: "manager";
+        viewer: "viewer";
+    }>;
+    assignedServices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    assignedGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    passwordHash: z.ZodOptional<z.ZodString>;
+    passwordEnv: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const loginBodySchema: z.ZodObject<{
+    name: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strip>;
+export declare const createUserSchema: z.ZodObject<{
+    username: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    role: z.ZodEnum<{
+        admin: "admin";
+        manager: "manager";
+        viewer: "viewer";
+    }>;
+    password: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const patchUserSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    role: z.ZodOptional<z.ZodEnum<{
+        admin: "admin";
+        manager: "manager";
+        viewer: "viewer";
+    }>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    password: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Per-assignment role is stored now for a future per-scope-role feature (CP16 §2.2). */
+export declare const userAssignmentsSchema: z.ZodObject<{
+    services: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        serviceId: z.ZodString;
+        role: z.ZodEnum<{
+            admin: "admin";
+            manager: "manager";
+            viewer: "viewer";
+        }>;
+    }, z.core.$strip>>>;
+    groups: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        groupId: z.ZodString;
+        role: z.ZodEnum<{
+            admin: "admin";
+            manager: "manager";
+            viewer: "viewer";
+        }>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Router param: validate BEFORE any scope/DB call => 400 on a malformed id. */
+export declare const userIdParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type ObserveUser = z.infer<typeof observeUserSchema>;
+export type LoginBody = z.infer<typeof loginBodySchema>;
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+export type PatchUserInput = z.infer<typeof patchUserSchema>;
+export type UserAssignmentsInput = z.infer<typeof userAssignmentsSchema>;

package/dist/runtime/shared/auth/schema.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { ROLES } from "./roles.js";
+export const roleSchema = z.enum(ROLES);
+export const assignmentSchema = z.object({
+  services: z.array(z.string().min(1)),
+  // slugs or ['*']
+  groups: z.array(z.string().min(1))
+});
+export const observeUserSchema = z.object({
+  name: z.string().min(1),
+  role: roleSchema,
+  assignedServices: z.array(z.string().min(1)).optional(),
+  assignedGroups: z.array(z.string().min(1)).optional(),
+  passwordHash: z.string().min(1).optional(),
+  passwordEnv: z.string().min(1).optional()
+}).refine((u) => !!(u.passwordHash || u.passwordEnv), {
+  message: "each observe.auth user needs passwordHash or passwordEnv"
+});
+export const loginBodySchema = z.object({
+  name: z.string().min(1),
+  password: z.string().min(1)
+});
+const passwordSchema = z.string().min(8).max(200);
+export const createUserSchema = z.object({
+  username: z.string().min(1).max(80),
+  displayName: z.string().min(1).max(120).optional(),
+  role: roleSchema,
+  password: passwordSchema.optional()
+  // absent => JWT-only / no local login
+});
+export const patchUserSchema = z.object({
+  displayName: z.string().min(1).max(120).nullable().optional(),
+  role: roleSchema.optional(),
+  disabled: z.boolean().optional(),
+  password: passwordSchema.optional()
+});
+export const userAssignmentsSchema = z.object({
+  services: z.array(z.object({ serviceId: z.string().min(1), role: roleSchema })).default([]),
+  groups: z.array(z.object({ groupId: z.string().min(1), role: roleSchema })).default([])
+});
+export const userIdParams = z.object({ id: z.string().min(1) });

package/dist/runtime/shared/auth/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Auth contract shared by app + server. Pure TS, no runtime imports beyond the
+ * inline h3 type — this file is pulled into both the Nitro server and the Nuxt
+ * app, and must stay dependency-free so neither side drags the other's runtime.
+ *
+ * This contract is FINAL for CP6 (RBAC enforcement + scoping) and CP16 (DB + JWT
+ * providers). Those checkpoints fill in behaviour behind these interfaces without
+ * changing a single field here or any call site. See CP5-HANDOFF §8.
+ */
+/** Access tiers. Ordered by privilege in ROLE_RANK (roles.ts). */
+export type Role = 'admin' | 'manager' | 'viewer';
+/**
+ * What a principal may see/act on. Slug arrays reference services.slug / groups.slug
+ * (CP2). The '*' sentinel (ALL, roles.ts) means "every service" / "every group" and
+ * is what an admin carries. CP6 reads this to scope every query; it never re-derives
+ * scope from the role alone.
+ */
+export interface Assignment {
+    /** service slugs, or ['*'] for all */
+    services: string[];
+    /** group slugs, or ['*'] for all */
+    groups: string[];
+}
+/**
+ * Provider-agnostic, session-shaped identity. This exact object is what
+ * setUserSession(event, { user: principal }) stores and requireObserveSession returns.
+ *   sub      stable identity: config -> user name; db -> row id; jwt -> `sub` claim
+ *   provider which AuthProvider minted it (audit + re-hydration routing for CP16).
+ *            'config' also tags the bootstrap-admin path (see roles.ts / CP16 notes).
+ */
+export interface Principal {
+    sub: string;
+    name: string;
+    role: Role;
+    assignment: Assignment;
+    provider: 'config' | 'db' | 'jwt';
+}
+/** Password login now; token login is the CP16 JWT path. Union so routes/providers stay forward-compatible. */
+export type Credentials = {
+    name: string;
+    password: string;
+} | {
+    token: string;
+};
+/** Uniform authenticate() outcome. `reason` is diagnostic only; never leak it to a 401 body. */
+export interface AuthenticateResult {
+    ok: boolean;
+    principal?: Principal;
+    reason?: string;
+}
+/**
+ * The extension point CP5 exists to establish. Every route authenticates through
+ * getAuthProvider().authenticate(). resolvePrincipal is optional session re-hydration
+ * (CP16 db/jwt use it to refresh role/assignment from the source of truth per request).
+ */
+export interface AuthProvider {
+    id: 'config' | 'db' | 'jwt';
+    authenticate(credentials: Credentials, event: import('h3').H3Event): Promise<AuthenticateResult>;
+    resolvePrincipal?(sub: string, event: import('h3').H3Event): Promise<Principal | null>;
+}
+/**
+ * Where a principal's Assignment comes from. CP5's ConfigAuthorizationStore returns
+ * principal.assignment verbatim (identity). CP16's db store looks assignments up by
+ * sub. CP6 adds capability checks HERE (documented in roles.ts, not implemented in CP5).
+ */
+export interface AuthorizationStore {
+    getAssignment(principal: Principal, event: import('h3').H3Event): Promise<Assignment>;
+}

package/dist/runtime/shared/rbac/capabilities.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Capability x scope authorization model, shared VERBATIM by server enforcement
+ * (server/utils/authz.ts) and client gating (app/composables/useObserveAbility.ts)
+ * so a gated control in the UI can never drift from what a route actually enforces.
+ *
+ * Framework-free: zod + the local auth contract only, no #imports / @nuxt/kit, so it
+ * loads identically in a node-env unit test, the Nitro server, and the browser.
+ *
+ * This implements the capability matrix DOCUMENTED (not enforced) in shared/auth/roles.ts.
+ * Two cells where that comment and the PLAN's CP6 table disagreed were resolved with the
+ * developer on 2026-07-06: `groups.manage` is admin-only, and `services.create` is split
+ * out of `services.manage` and is admin-only. See CP6-HANDOFF §9.2/§9.3.
+ */
+import { z } from 'zod';
+import type { Role } from '../auth/types.js';
+import { roleSchema } from '../auth/schema.js';
+/** What a held capability applies to. Absence from the matrix === 'none' (denied). */
+export type Scope = 'all' | 'assigned' | 'none';
+export type Capability = 'users.manage' | 'services.create' | 'services.manage' | 'groups.manage' | 'migrations.manage' | 'services.read' | 'logs.read' | 'stats.read';
+export declare const CAPABILITIES: readonly ["users.manage", "services.create", "services.manage", "groups.manage", "migrations.manage", "services.read", "logs.read", "stats.read"];
+export declare const scopeSchema: z.ZodEnum<{
+    none: "none";
+    all: "all";
+    assigned: "assigned";
+}>;
+export declare const capabilitySchema: z.ZodEnum<{
+    "users.manage": "users.manage";
+    "services.create": "services.create";
+    "services.manage": "services.manage";
+    "groups.manage": "groups.manage";
+    "migrations.manage": "migrations.manage";
+    "services.read": "services.read";
+    "logs.read": "logs.read";
+    "stats.read": "stats.read";
+}>;
+export { roleSchema };
+/**
+ * (role, capability) -> scope. A capability ABSENT from a role's map is scope 'none':
+ * that role is denied it entirely (=> 403 at the choke point). The 'assigned' scope is
+ * short-circuited to unrestricted at resolution time when the principal carries a '*'
+ * assignment (getAllowedServiceIds); admin holds every capability at 'all'.
+ */
+export declare const ROLE_CAPABILITIES: Record<Role, Partial<Record<Capability, Scope>>>;
+/** The one resolver both server and client call. Returns the scope, or undefined when denied. */
+export declare function roleCan(role: Role, capability: Capability): Scope | undefined;
+export declare function hasCapability(role: Role, capability: Capability): boolean;

package/dist/runtime/shared/rbac/capabilities.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { roleSchema } from "../auth/schema.js";
+export const CAPABILITIES = [
+  "users.manage",
+  "services.create",
+  "services.manage",
+  "groups.manage",
+  "migrations.manage",
+  "services.read",
+  "logs.read",
+  "stats.read"
+];
+export const scopeSchema = z.enum(["all", "assigned", "none"]);
+export const capabilitySchema = z.enum(CAPABILITIES);
+export { roleSchema };
+export const ROLE_CAPABILITIES = {
+  admin: {
+    "users.manage": "all",
+    "services.create": "all",
+    "services.manage": "all",
+    "groups.manage": "all",
+    "migrations.manage": "all",
+    "services.read": "all",
+    "logs.read": "all",
+    "stats.read": "all"
+  },
+  manager: {
+    "services.manage": "assigned",
+    "services.read": "assigned",
+    "logs.read": "assigned",
+    "stats.read": "assigned"
+    // groups.manage absent => 'none': group management is admin-only (§9.2).
+    // services.create absent => 'none': a brand-new service has no assignment to scope
+    // a manager against, so creating one is admin-only (§9.3); a manager still edits
+    // (services.manage) the services already assigned to it.
+  },
+  viewer: {
+    "services.read": "assigned",
+    "logs.read": "assigned",
+    "stats.read": "assigned"
+  }
+};
+export function roleCan(role, capability) {
+  return ROLE_CAPABILITIES[role]?.[capability];
+}
+export function hasCapability(role, capability) {
+  return roleCan(role, capability) !== void 0;
+}