@frockbot/plugin-admin 0.0.0 → 0.1.1

package/frockbot.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 3,
+  "id": "admin",
+  "displayName": "Deployment administration",
+  "version": "0.0.1",
+  "compatibility": { "frockbot": ">=0.0.1" },
+  "dependencies": {
+    "shell": ">=0.0.1",
+    "ui-theme": ">=0.0.1"
+  },
+  "contributions": {
+    "backend": [{ "entry": "./backend", "host": "gateway" }],
+    "client": { "entry": "./client", "mounts": [], "outlets": [] }
+  },
+  "permissions": []
+}

package/package.json

@@ -1,14 +1,42 @@
 {
   "name": "@frockbot/plugin-admin",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./backend": "./src/backend.ts",
+    "./client": "./src/client/index.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./manifest": "./src/manifest.ts",
+    "./package.json": "./package.json",
+    "./shared": "./src/shared.ts"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/client-core": "0.1.1",
+    "@frockbot/client-ui": "0.1.1",
+    "@frockbot/plugin-shell": "0.1.1",
+    "cordis": "4.0.0-rc.8",
+    "vue": "3.5.41"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "typescript": "5.9.3",
+    "vue-tsc": "3.3.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-admin"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/backend.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+import { createAdminBackendContribution } from "./backend.js";
+import {
+  DeploymentPolicyConflictError,
+  type DeploymentPolicyV1,
+} from "./shared.js";
+
+function initialPolicy(): DeploymentPolicyV1 {
+  return {
+    schemaVersion: 1,
+    revision: 0,
+    signups: { open: false },
+    updatedAt: "2026-09-01T00:00:00.000Z",
+    updatedBy: "deployment-default",
+  };
+}
+
+describe("admin gateway contribution", () => {
+  test("refuses non-admins before reading deployment policy", async () => {
+    let reads = 0;
+    const contribution = createAdminBackendContribution({
+      readDeploymentPolicy: () => {
+        reads += 1;
+        return Promise.resolve(initialPolicy());
+      },
+      setDeploymentSignups: () => Promise.resolve(initialPolicy()),
+    });
+
+    const response = await contribution.route(
+      new Request("https://frockbot.test/api/admin/policy"),
+      new URL("https://frockbot.test/api/admin/policy"),
+      { userId: "ordinary-user", client: "browser", isAdmin: false },
+    );
+
+    expect(response?.status).toBe(403);
+    expect(reads).toBe(0);
+  });
+
+  test("reads and updates the policy with an optimistic revision", async () => {
+    let policy = initialPolicy();
+    const contribution = createAdminBackendContribution({
+      readDeploymentPolicy: () => Promise.resolve(policy),
+      setDeploymentSignups: (command, updatedBy) => {
+        if (command.revision !== policy.revision) {
+          throw new DeploymentPolicyConflictError(policy.revision);
+        }
+        policy = {
+          schemaVersion: 1,
+          revision: policy.revision + 1,
+          signups: { open: command.open },
+          updatedAt: "2026-09-01T01:00:00.000Z",
+          updatedBy,
+        };
+        return Promise.resolve(policy);
+      },
+    });
+    const context = {
+      userId: "owner-id",
+      client: "browser" as const,
+      isAdmin: true,
+    };
+
+    const read = await contribution.route(
+      new Request("https://frockbot.test/api/admin/policy"),
+      new URL("https://frockbot.test/api/admin/policy"),
+      context,
+    );
+    expect(await read?.json()).toEqual(initialPolicy());
+
+    const update = await contribution.route(
+      new Request("https://frockbot.test/api/admin/policy", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          schemaVersion: 1,
+          type: "deployment/set-signups",
+          open: true,
+          revision: 0,
+        }),
+      }),
+      new URL("https://frockbot.test/api/admin/policy"),
+      context,
+    );
+    expect(update?.status).toBe(200);
+    expect(await update?.json()).toMatchObject({
+      revision: 1,
+      signups: { open: true },
+      updatedBy: "owner-id",
+    });
+
+    const conflict = await contribution.route(
+      new Request("https://frockbot.test/api/admin/policy", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          schemaVersion: 1,
+          type: "deployment/set-signups",
+          open: false,
+          revision: 0,
+        }),
+      }),
+      new URL("https://frockbot.test/api/admin/policy"),
+      context,
+    );
+    expect(conflict?.status).toBe(409);
+    expect(await conflict?.json()).toMatchObject({
+      code: "revision-conflict",
+      currentRevision: 1,
+    });
+  });
+});

package/src/backend.ts

@@ -0,0 +1,120 @@
+import type { Plugin } from "cordis";
+import {
+  decodeDeploymentPolicyV1,
+  decodeSetSignupsCommandV1,
+  type DeploymentPolicyV1,
+  type SetSignupsCommandV1,
+} from "./shared.js";
+
+export interface AdminGatewayHost {
+  readDeploymentPolicy(): Promise<DeploymentPolicyV1>;
+  setDeploymentSignups(
+    command: SetSignupsCommandV1,
+    updatedBy: string,
+  ): Promise<DeploymentPolicyV1>;
+}
+
+export interface AdminBackendRouteContribution {
+  packageId: string;
+  route(
+    request: Request,
+    url: URL,
+    context: {
+      userId?: string;
+      client: "browser" | "desktop";
+      isAdmin: boolean;
+    },
+  ): Promise<Response | undefined>;
+}
+
+function jsonError(status: number, message: string): Response {
+  return Response.json({ error: message }, { status });
+}
+
+function isPolicyConflict(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    error.name === "DeploymentPolicyConflictError"
+  );
+}
+
+export function createAdminBackendContribution(
+  host: AdminGatewayHost,
+): AdminBackendRouteContribution {
+  return {
+    packageId: "admin",
+    async route(request, url, context) {
+      if (url.pathname !== "/api/admin/policy") return undefined;
+      if (!context.userId || !context.isAdmin) {
+        return jsonError(403, "Admin access is required");
+      }
+      if ([...url.searchParams.keys()].length > 0) {
+        return jsonError(400, "Admin policy query is invalid");
+      }
+      if (request.method === "GET") {
+        try {
+          return Response.json(
+            decodeDeploymentPolicyV1(await host.readDeploymentPolicy()),
+          );
+        } catch (error) {
+          return jsonError(
+            500,
+            error instanceof Error
+              ? error.message
+              : "Admin policy could not be read",
+          );
+        }
+      }
+      if (request.method !== "POST") {
+        return jsonError(405, "method not allowed");
+      }
+      let command: SetSignupsCommandV1;
+      try {
+        command = decodeSetSignupsCommandV1(await request.json());
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "Admin policy was refused",
+        );
+      }
+      try {
+        return Response.json(
+          decodeDeploymentPolicyV1(
+            await host.setDeploymentSignups(command, context.userId),
+          ),
+        );
+      } catch (error) {
+        if (isPolicyConflict(error)) {
+          const current = decodeDeploymentPolicyV1(
+            await host.readDeploymentPolicy(),
+          );
+          return Response.json(
+            {
+              error: `deployment policy revision is ${current.revision}`,
+              code: "revision-conflict",
+              currentRevision: current.revision,
+            },
+            { status: 409 },
+          );
+        }
+        return jsonError(
+          500,
+          error instanceof Error
+            ? error.message
+            : "Admin policy could not be changed",
+        );
+      }
+    },
+  };
+}
+
+export namespace createAdminBackendContribution {
+  export function plugin(
+    host: AdminGatewayHost,
+    lifecycle: { mount(value: AdminBackendRouteContribution): () => void },
+  ): Plugin {
+    return () => lifecycle.mount(createAdminBackendContribution(host));
+  }
+}

package/src/client/AdminSurface.vue

@@ -0,0 +1,178 @@
+<script setup lang="ts">
+import { UiButton } from "@frockbot/client-ui";
+import { inject, onMounted, ref } from "vue";
+import {
+  decodeDeploymentPolicyV1,
+  type DeploymentPolicyV1,
+} from "../shared.js";
+import { adminRequestKey } from "./state.js";
+
+const providedRequest = inject(adminRequestKey);
+if (!providedRequest)
+  throw new Error("admin client transport was not provided");
+const request: NonNullable<typeof providedRequest> = providedRequest;
+
+const policy = ref<DeploymentPolicyV1>();
+const loading = ref(true);
+const saving = ref(false);
+const error = ref<string>();
+
+function changedLine(value: DeploymentPolicyV1): string {
+  const changed = new Intl.DateTimeFormat(undefined, {
+    dateStyle: "medium",
+    timeStyle: "short",
+  }).format(new Date(value.updatedAt));
+  return `Last changed ${changed} by ${value.updatedBy}.`;
+}
+
+async function load(): Promise<void> {
+  loading.value = true;
+  try {
+    policy.value = decodeDeploymentPolicyV1(await request("/api/admin/policy"));
+    error.value = undefined;
+  } catch (cause) {
+    error.value =
+      cause instanceof Error ? cause.message : "Could not load signup policy";
+  } finally {
+    loading.value = false;
+  }
+}
+
+async function setOpen(open: boolean): Promise<void> {
+  const current = policy.value;
+  if (!current || saving.value || current.signups.open === open) return;
+  saving.value = true;
+  error.value = undefined;
+  try {
+    policy.value = decodeDeploymentPolicyV1(
+      await request(
+        "/api/admin/policy",
+        "POST",
+        JSON.stringify({
+          schemaVersion: 1,
+          type: "deployment/set-signups",
+          open,
+          revision: current.revision,
+        }),
+      ),
+    );
+  } catch (cause) {
+    const message =
+      cause instanceof Error ? cause.message : "Could not change signup policy";
+    await load();
+    error.value = message;
+  } finally {
+    saving.value = false;
+  }
+}
+
+function changeSignups(event: Event): void {
+  const target = event.currentTarget;
+  if (!(target instanceof HTMLInputElement)) return;
+  void setOpen(target.checked);
+}
+
+onMounted(load);
+</script>
+
+<template>
+  <section class="admin-surface" aria-label="Deployment policy">
+    <p class="admin-surface__explanation">
+      Control whether people without an existing FrockBot User can sign in.
+      Existing Users and admins are always admitted.
+    </p>
+
+    <p v-if="loading" class="admin-surface__status" aria-live="polite">
+      Loading signup policy…
+    </p>
+
+    <div v-else-if="policy" class="admin-surface__policy">
+      <label class="admin-surface__toggle">
+        <span>
+          <strong>Accept new signups</strong>
+          <small>Let new Users enter this deployment.</small>
+        </span>
+        <input
+          type="checkbox"
+          :checked="policy.signups.open"
+          :disabled="saving"
+          @change="changeSignups"
+        />
+      </label>
+      <p class="admin-surface__changed">{{ changedLine(policy) }}</p>
+    </div>
+
+    <p v-if="error" class="admin-surface__error" role="alert">{{ error }}</p>
+    <UiButton v-if="error && !policy" type="button" @click="load">
+      Try again
+    </UiButton>
+  </section>
+</template>
+
+<style scoped>
+.admin-surface {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 16px;
+}
+
+.admin-surface__explanation,
+.admin-surface__status,
+.admin-surface__changed,
+.admin-surface__error {
+  margin: 0;
+  font-size: var(--frock-text-sm);
+  line-height: var(--frock-leading-normal);
+}
+
+.admin-surface__explanation,
+.admin-surface__status,
+.admin-surface__changed {
+  color: var(--frock-text-muted);
+}
+
+.admin-surface__policy {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 14px;
+  border: 1px solid var(--frock-border);
+  border-radius: var(--frock-radius-card);
+  background: var(--frock-surface-subtle);
+}
+
+.admin-surface__toggle {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  cursor: pointer;
+}
+
+.admin-surface__toggle span {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+
+.admin-surface__toggle strong {
+  font-size: var(--frock-text-md);
+  font-weight: 600;
+}
+
+.admin-surface__toggle small {
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-sm);
+}
+
+.admin-surface__toggle input {
+  width: var(--frock-control-sm);
+  height: var(--frock-control-sm);
+  accent-color: var(--frock-action-primary);
+}
+
+.admin-surface__error {
+  color: var(--frock-danger-text);
+}
+</style>

package/src/client/index.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import {
+  clientSurfaceRegistryKey,
+  type ClientPluginContext,
+} from "@frockbot/client-core";
+import { createClientSurfaceRegistry } from "@frockbot/client-ui";
+import { adminClientPlugin } from "./index.js";
+
+describe("admin client contribution", () => {
+  test("registers and disposes the Admin overlay", () => {
+    const surfaces = createClientSurfaceRegistry();
+    const context: ClientPluginContext = {
+      transport: {
+        turn: () => Promise.resolve({ runId: "run", text: "", events: [] }),
+        hostedRequest: () => Promise.resolve({}),
+      },
+      inject: (key) => {
+        if (key !== clientSurfaceRegistryKey) {
+          throw new Error("unexpected client provider");
+        }
+        return surfaces as never;
+      },
+      provide: () => () => {},
+      slot: () => () => {},
+    };
+
+    const result = adminClientPlugin(context);
+    if (!Array.isArray(result)) throw new Error("expected owned registrations");
+    expect(surfaces.has("admin")).toBe(true);
+
+    for (const dispose of result.toReversed()) dispose();
+    expect(surfaces.has("admin")).toBe(false);
+  });
+});

package/src/client/index.ts

@@ -0,0 +1,28 @@
+/// <reference path="../env.d.ts" />
+
+import {
+  clientSurfaceRegistryKey,
+  type ClientPlugin,
+} from "@frockbot/client-core";
+import AdminSurface from "./AdminSurface.vue";
+import { adminRequestKey } from "./state.js";
+
+export const ADMIN_SURFACE_ID = "admin";
+
+export const adminClientPlugin: ClientPlugin = (ctx) => {
+  if (!ctx.transport.hostedRequest) {
+    throw new Error("Admin hosted transport is unavailable");
+  }
+  const request = ctx.transport.hostedRequest.bind(ctx.transport);
+  const surfaces = ctx.inject(clientSurfaceRegistryKey);
+  return [
+    ctx.provide(adminRequestKey, request),
+    surfaces.register({
+      id: ADMIN_SURFACE_ID,
+      title: "Admin",
+      component: AdminSurface,
+    }),
+  ];
+};
+
+export default adminClientPlugin;

package/src/client/state.ts

@@ -0,0 +1,11 @@
+import type { InjectionKey } from "vue";
+
+export type AdminRequest = (
+  path: string,
+  method?: "GET" | "POST",
+  body?: string,
+) => Promise<unknown>;
+
+export const adminRequestKey: InjectionKey<AdminRequest> = Symbol(
+  "frockbot.admin-request",
+);

package/src/env.d.ts

@@ -0,0 +1,6 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+
+  const component: DefineComponent;
+  export default component;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { default as manifest } from "./manifest.js";
+export * from "./shared.js";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;

package/src/shared.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeDeploymentPolicyV1,
+  decodeSetSignupsCommandV1,
+  decodeSetSignupsRequestV1,
+} from "./shared.js";
+
+const policy = {
+  schemaVersion: 1,
+  revision: 2,
+  signups: { open: false },
+  updatedAt: "2026-09-01T00:00:00.000Z",
+  updatedBy: "owner@example.com",
+} as const;
+
+describe("deployment policy codecs", () => {
+  test("decode the exact policy and signup command shapes", () => {
+    expect(decodeDeploymentPolicyV1(policy)).toEqual(policy);
+    expect(
+      decodeSetSignupsCommandV1({
+        schemaVersion: 1,
+        type: "deployment/set-signups",
+        open: true,
+        revision: 2,
+      }),
+    ).toEqual({
+      schemaVersion: 1,
+      type: "deployment/set-signups",
+      open: true,
+      revision: 2,
+    });
+    expect(
+      decodeSetSignupsRequestV1({
+        schemaVersion: 1,
+        command: {
+          schemaVersion: 1,
+          type: "deployment/set-signups",
+          open: true,
+          revision: 2,
+        },
+        updatedBy: "owner-id",
+      }),
+    ).toMatchObject({ updatedBy: "owner-id", command: { open: true } });
+  });
+
+  test("rejects unknown fields at every seam", () => {
+    expect(() => decodeDeploymentPolicyV1({ ...policy, extra: true })).toThrow(
+      "unknown fields",
+    );
+    expect(() =>
+      decodeDeploymentPolicyV1({
+        ...policy,
+        signups: { open: false, extra: true },
+      }),
+    ).toThrow("unknown fields");
+    expect(() =>
+      decodeSetSignupsCommandV1({
+        schemaVersion: 1,
+        type: "deployment/set-signups",
+        open: true,
+        revision: 2,
+        expectedRevision: 2,
+      }),
+    ).toThrow("unknown fields");
+  });
+});

package/src/shared.ts

@@ -0,0 +1,162 @@
+export interface DeploymentPolicyV1 {
+  schemaVersion: 1;
+  revision: number;
+  signups: { open: boolean };
+  updatedAt: string;
+  updatedBy: string;
+}
+
+export interface SetSignupsCommandV1 {
+  schemaVersion: 1;
+  type: "deployment/set-signups";
+  open: boolean;
+  revision: number;
+}
+
+export interface SetSignupsRequestV1 {
+  schemaVersion: 1;
+  command: SetSignupsCommandV1;
+  updatedBy: string;
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(
+  value: Record<string, unknown>,
+  expected: readonly string[],
+  label: string,
+): void {
+  const keys = Object.keys(value);
+  if (
+    keys.length !== expected.length ||
+    !keys.every((key) => expected.includes(key))
+  ) {
+    throw new Error(`${label} has unknown fields`);
+  }
+}
+
+function revision(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new Error(`${label} is invalid`);
+  }
+  return value as number;
+}
+
+function boundedString(value: unknown, label: string, maximum: number): string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > maximum
+  ) {
+    throw new Error(`${label} is invalid`);
+  }
+  return value;
+}
+
+function isoTimestamp(value: unknown, label: string): string {
+  const timestamp = boundedString(value, label, 64);
+  if (
+    !Number.isFinite(Date.parse(timestamp)) ||
+    new Date(timestamp).toISOString() !== timestamp
+  ) {
+    throw new Error(`${label} is invalid`);
+  }
+  return timestamp;
+}
+
+export function decodeDeploymentPolicyV1(input: unknown): DeploymentPolicyV1 {
+  const policy = record(input, "deployment policy");
+  exactKeys(
+    policy,
+    ["schemaVersion", "revision", "signups", "updatedAt", "updatedBy"],
+    "deployment policy",
+  );
+  if (policy.schemaVersion !== 1) {
+    throw new Error("deployment policy.schemaVersion is invalid");
+  }
+  const signups = record(policy.signups, "deployment policy.signups");
+  exactKeys(signups, ["open"], "deployment policy.signups");
+  if (typeof signups.open !== "boolean") {
+    throw new Error("deployment policy.signups.open is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    revision: revision(policy.revision, "deployment policy.revision"),
+    signups: { open: signups.open },
+    updatedAt: isoTimestamp(policy.updatedAt, "deployment policy.updatedAt"),
+    updatedBy: boundedString(
+      policy.updatedBy,
+      "deployment policy.updatedBy",
+      512,
+    ),
+  };
+}
+
+export function decodeSetSignupsCommandV1(input: unknown): SetSignupsCommandV1 {
+  const command = record(input, "deployment signup command");
+  exactKeys(
+    command,
+    ["schemaVersion", "type", "open", "revision"],
+    "deployment signup command",
+  );
+  if (
+    command.schemaVersion !== 1 ||
+    command.type !== "deployment/set-signups" ||
+    typeof command.open !== "boolean"
+  ) {
+    throw new Error("deployment signup command is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    type: "deployment/set-signups",
+    open: command.open,
+    revision: revision(command.revision, "deployment signup command.revision"),
+  };
+}
+
+export function decodeDeploymentPolicyReadRequestV1(input: unknown): {
+  schemaVersion: 1;
+} {
+  const request = record(input, "deployment policy read request");
+  exactKeys(request, ["schemaVersion"], "deployment policy read request");
+  if (request.schemaVersion !== 1) {
+    throw new Error("deployment policy read request.schemaVersion is invalid");
+  }
+  return { schemaVersion: 1 };
+}
+
+export function decodeSetSignupsRequestV1(input: unknown): SetSignupsRequestV1 {
+  const request = record(input, "deployment signup request");
+  exactKeys(
+    request,
+    ["schemaVersion", "command", "updatedBy"],
+    "deployment signup request",
+  );
+  if (request.schemaVersion !== 1) {
+    throw new Error("deployment signup request.schemaVersion is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    command: decodeSetSignupsCommandV1(request.command),
+    updatedBy: boundedString(
+      request.updatedBy,
+      "deployment signup request.updatedBy",
+      512,
+    ),
+  };
+}
+
+export class DeploymentPolicyConflictError extends Error {
+  readonly currentRevision: number;
+
+  constructor(currentRevision: number) {
+    super(`deployment policy revision is ${currentRevision}`);
+    this.name = "DeploymentPolicyConflictError";
+    this.currentRevision = currentRevision;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/plugin-admin
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.