@frockbot/plugin-auth 0.0.0 → 0.1.1

package/src/client/session.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "bun:test";
+import { decodeAuthSessionProjectionV1 } from "../shared.js";
+import { createAuthSessionClient } from "./session.js";
+
+const authenticated = {
+  schemaVersion: 1,
+  status: "authenticated",
+  mode: "better-auth",
+  user: {
+    id: "alice",
+    name: "Alice",
+    email: "alice@example.com",
+    isAdmin: false,
+  },
+} as const;
+
+describe("auth session projection", () => {
+  test("strictly decodes exact session modes", () => {
+    expect(decodeAuthSessionProjectionV1(authenticated)).toEqual(authenticated);
+    expect(
+      decodeAuthSessionProjectionV1({ schemaVersion: 1, status: "anonymous" }),
+    ).toEqual({ schemaVersion: 1, status: "anonymous" });
+
+    for (const invalid of [
+      { ...authenticated, extra: true },
+      { ...authenticated, user: { ...authenticated.user, extra: true } },
+      { ...authenticated, mode: "cookie" },
+    ]) {
+      expect(() => decodeAuthSessionProjectionV1(invalid)).toThrow();
+    }
+    const hidden = { ...authenticated } as Record<PropertyKey, unknown>;
+    Object.defineProperty(hidden, "hidden", { value: true });
+    expect(() => decodeAuthSessionProjectionV1(hidden)).toThrow();
+    expect(() =>
+      decodeAuthSessionProjectionV1({
+        ...authenticated,
+        [Symbol("hidden")]: true,
+      }),
+    ).toThrow();
+  });
+});
+
+describe("auth-owned sign-out", () => {
+  test("serializes double-click, refreshes authority, and is safely repeatable", async () => {
+    let current: unknown = authenticated;
+    let calls = 0;
+    let release: (() => void) | undefined;
+    const pending = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const session = createAuthSessionClient({
+      read: () => Promise.resolve(current),
+      signOut: async () => {
+        calls += 1;
+        await pending;
+        current = { schemaVersion: 1, status: "anonymous" };
+        return current;
+      },
+    });
+    await session.refresh();
+
+    const first = session.signOut();
+    const second = session.signOut();
+    expect(session.signingOut.value).toBe(true);
+    expect(calls).toBe(1);
+    release?.();
+    await Promise.all([first, second]);
+
+    expect(session.projection.value).toEqual({
+      schemaVersion: 1,
+      status: "anonymous",
+    });
+    expect(session.signingOut.value).toBe(false);
+    await session.signOut();
+    expect(calls).toBe(1);
+  });
+
+  test("keeps the authenticated projection when sign-out fails", async () => {
+    const session = createAuthSessionClient({
+      read: () => Promise.resolve(authenticated),
+      signOut: () => Promise.reject(new Error("network unavailable")),
+    });
+    await session.refresh();
+
+    await expect(session.signOut()).rejects.toThrow("network unavailable");
+    expect(session.projection.value).toEqual(authenticated);
+    expect(session.signingOut.value).toBe(false);
+  });
+
+  test("makes development identity sign-out explicitly unavailable", async () => {
+    let calls = 0;
+    const session = createAuthSessionClient({
+      read: () =>
+        Promise.resolve({
+          ...authenticated,
+          mode: "development",
+        }),
+      signOut: () => {
+        calls += 1;
+        return Promise.resolve({ schemaVersion: 1, status: "anonymous" });
+      },
+    });
+    await session.refresh();
+
+    await expect(session.signOut()).rejects.toThrow(
+      "Development identity is selected by the local development login",
+    );
+    expect(calls).toBe(0);
+  });
+
+  test("requires authoritative anonymous state after successful sign-out", async () => {
+    const session = createAuthSessionClient({
+      read: () => Promise.resolve(authenticated),
+      signOut: () => Promise.resolve(authenticated),
+    });
+    await session.refresh();
+
+    await expect(session.signOut()).rejects.toThrow(
+      "Sign-out did not clear the authenticated session",
+    );
+    expect(session.projection.value).toEqual(authenticated);
+  });
+});

package/src/client/session.ts

@@ -0,0 +1,67 @@
+import { readonly, ref } from "vue";
+import {
+  decodeAuthSessionProjectionV1,
+  type AuthSessionClient,
+  type AuthSessionProjectionV1,
+} from "../shared.js";
+
+export interface AuthSessionAdapter {
+  read(): Promise<unknown>;
+  /** Returns the authoritative post-command auth projection. */
+  signOut(): Promise<unknown>;
+}
+
+export function createAuthSessionClient(
+  adapter: AuthSessionAdapter,
+): AuthSessionClient {
+  const projection = ref<AuthSessionProjectionV1>({
+    schemaVersion: 1,
+    status: "loading",
+  });
+  const signingOut = ref(false);
+  let pendingSignOut: Promise<void> | undefined;
+
+  const refresh = async (): Promise<void> => {
+    projection.value = decodeAuthSessionProjectionV1(await adapter.read());
+  };
+
+  const signOut = (): Promise<void> => {
+    if (pendingSignOut) return pendingSignOut;
+    const current = projection.value;
+    if (current.status === "anonymous") return Promise.resolve();
+    if (current.status === "loading") {
+      return Promise.reject(new Error("Authentication is still loading"));
+    }
+    if (current.mode === "development") {
+      return Promise.reject(
+        new Error(
+          "Development identity is selected by the local development login and cannot be signed out",
+        ),
+      );
+    }
+
+    signingOut.value = true;
+    pendingSignOut = (async () => {
+      try {
+        const authoritative = decodeAuthSessionProjectionV1(
+          await adapter.signOut(),
+        );
+        if (authoritative.status !== "anonymous") {
+          throw new Error("Sign-out did not clear the authenticated session");
+        }
+        projection.value = authoritative;
+      } finally {
+        signingOut.value = false;
+        pendingSignOut = undefined;
+      }
+    })();
+    return pendingSignOut;
+  };
+
+  return {
+    projection: readonly(projection),
+    signingOut: readonly(signingOut),
+    refresh,
+    signOut,
+  };
+}

package/src/client/styles.css

@@ -0,0 +1,171 @@
+.auth-screen {
+  display: grid;
+  width: 100%;
+  height: 100%;
+  place-items: center;
+  padding: 32px;
+  color: var(--frock-text);
+  background: var(--frock-auth-background), var(--frock-surface-window);
+  font-family:
+    Manrope,
+    ui-sans-serif,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+}
+
+.auth-card {
+  width: min(100%, 410px);
+  padding: 44px;
+  border: 1px solid var(--frock-border);
+  border-radius: 24px;
+  background: var(--frock-surface-raised);
+  box-shadow: var(--frock-shadow-auth);
+  text-align: center;
+}
+
+.auth-mark {
+  display: grid;
+  width: 56px;
+  height: 56px;
+  place-items: center;
+  margin: 0 auto 22px;
+  border-radius: 18px;
+  color: var(--frock-action-primary-hover);
+  background: var(--frock-surface-accent);
+  font-size: var(--frock-text-display);
+  font-weight: 700;
+}
+
+.auth-eyebrow {
+  margin: 0 0 9px;
+  color: var(--frock-action-primary-hover);
+  font-size: var(--frock-text-sm);
+  font-weight: 800;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+}
+
+.auth-card h1 {
+  margin: 0;
+  color: var(--frock-text);
+  font-family: "Archivo Black", Manrope, sans-serif;
+  font-size: var(--frock-text-display);
+  font-weight: 400;
+  letter-spacing: -0.05em;
+}
+
+.auth-copy {
+  margin: 13px 0 30px;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-md);
+  line-height: 1.6;
+}
+
+.auth-actions {
+  display: grid;
+  gap: 11px;
+}
+
+.google-button,
+.dev-button {
+  display: flex;
+  width: 100%;
+  min-height: 50px;
+  align-items: center;
+  justify-content: center;
+  gap: 11px;
+  border: 1px solid var(--frock-border);
+  border-radius: 999px;
+  color: var(--frock-text);
+  background: var(--frock-surface-subtle);
+  font-weight: 700;
+  cursor: pointer;
+  transition:
+    transform 180ms ease,
+    background 180ms ease,
+    border-color 180ms ease;
+}
+
+.dev-button {
+  border-color: var(--frock-action-primary);
+  color: var(--frock-on-accent);
+  background: var(--frock-action-primary);
+  box-shadow: var(--frock-shadow-accent);
+}
+
+.google-button:hover:not(:disabled) {
+  border-color: var(--frock-border-strong);
+  background: var(--frock-surface-subtle);
+  transform: translateY(-1px);
+}
+
+.dev-button:hover:not(:disabled) {
+  border-color: var(--frock-action-primary-hover);
+  background: var(--frock-action-primary-hover);
+  transform: translateY(-1px);
+}
+
+.google-button:focus-visible,
+.dev-button:focus-visible {
+  outline: 3px solid var(--frock-focus-ring);
+  outline-offset: 3px;
+}
+
+.google-button:disabled,
+.dev-button:disabled {
+  box-shadow: none;
+  cursor: wait;
+}
+
+.google-button:disabled {
+  color: var(--frock-text-subtle);
+}
+
+.dev-button:disabled {
+  color: var(--frock-on-accent);
+  opacity: 0.62;
+}
+
+.google-g {
+  display: grid;
+  width: 23px;
+  height: 23px;
+  place-items: center;
+  border: 1px solid var(--frock-border);
+  border-radius: 50%;
+  color: var(--frock-provider-google);
+  background: var(--frock-surface-subtle);
+  font-family: Arial, sans-serif;
+  font-size: var(--frock-text-md);
+  font-weight: 700;
+}
+
+.auth-loading,
+.auth-hint,
+.auth-error {
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-base);
+  line-height: 1.5;
+}
+
+.auth-loading {
+  min-height: 46px;
+}
+
+.auth-hint,
+.auth-error {
+  margin: 16px 0 0;
+}
+
+.auth-error {
+  color: var(--frock-danger-text);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .google-button,
+  .dev-button {
+    transition: none;
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+
+import { verifyPluginPackage } from "@frockbot/plugin-testkit";
+import manifest from "../frockbot.json" with { type: "json" };
+import packageJson from "../package.json" with { type: "json" };
+
+test("auth satisfies plugin package conventions", () => {
+  expect(verifyPluginPackage({ packageJson, manifest })).toMatchObject({
+    name: "@frockbot/plugin-auth",
+    contributionKinds: ["client", "desktop"],
+  });
+});

package/src/desktop.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { createPluginHarness } from "@frockbot/plugin-testkit";
+import manifest from "../frockbot.json" with { type: "json" };
+import desktopAuthPlugin, { DesktopAuthCapability } from "./desktop.js";
+
+class FakeDesktopAuthCapability extends DesktopAuthCapability {
+  starts = 0;
+  stops = 0;
+
+  start(): () => void {
+    this.starts += 1;
+    return () => {
+      this.stops += 1;
+    };
+  }
+}
+
+describe("desktop authentication Contribution", () => {
+  test("declares one trusted main-process Contribution", () => {
+    expect(manifest.schemaVersion).toBe(3);
+    expect(manifest.contributions.desktop).toEqual({
+      entry: "./desktop",
+      execution: "trusted-main",
+      commands: [],
+    });
+  });
+
+  test("owns setup and cleanup for its mounted lifetime", async () => {
+    const harness = await createPluginHarness([FakeDesktopAuthCapability]);
+    const capability = harness.root
+      .desktopAuthCapability as FakeDesktopAuthCapability;
+
+    const mounted = await harness.mount(desktopAuthPlugin);
+    expect(capability.starts).toBe(1);
+    expect(capability.stops).toBe(0);
+
+    await mounted.dispose();
+    expect(capability.stops).toBe(1);
+  });
+});

package/src/desktop.ts

@@ -0,0 +1,21 @@
+import { type Context, type Plugin, Service } from "cordis";
+
+export abstract class DesktopAuthCapability extends Service {
+  constructor(ctx: Context) {
+    super(ctx, "desktopAuthCapability");
+  }
+
+  abstract start(): () => void;
+}
+
+declare module "cordis" {
+  interface Context {
+    desktopAuthCapability: DesktopAuthCapability;
+  }
+}
+
+export const desktopAuthPlugin: Plugin.Function = (ctx) =>
+  ctx.desktopAuthCapability.start();
+desktopAuthPlugin.inject = ["desktopAuthCapability"];
+
+export default desktopAuthPlugin;

package/src/development-login.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import {
+  developmentLoginUrl,
+  developmentUserFromUrl,
+  isLoopbackHost,
+} from "./client/development-login";
+
+describe("development login", () => {
+  test("is available only on loopback hosts", () => {
+    expect(isLoopbackHost("localhost")).toBe(true);
+    expect(isLoopbackHost("127.0.0.1")).toBe(true);
+    expect(isLoopbackHost("::1")).toBe(true);
+    expect(isLoopbackHost("frockbot.example.com")).toBe(false);
+  });
+
+  test("recognizes only the fixed development identity", () => {
+    expect(
+      developmentUserFromUrl(
+        new URL("http://localhost:5173/?as_user=development"),
+      ),
+    ).toBe("development");
+    expect(
+      developmentUserFromUrl(new URL("http://localhost:5173/?as_user=alice")),
+    ).toBeUndefined();
+    expect(
+      developmentUserFromUrl(
+        new URL("https://frockbot.example.com/?as_user=development"),
+      ),
+    ).toBeUndefined();
+  });
+
+  test("builds a login URL without dropping existing state", () => {
+    expect(
+      developmentLoginUrl(new URL("http://localhost:5173/?bot=demo#chat")),
+    ).toBe("http://localhost:5173/?bot=demo&as_user=development#chat");
+  });
+});

package/src/env.d.ts

@@ -0,0 +1,43 @@
+/// <reference types="vite/client" />
+
+interface DesktopAuthUser {
+  id: string;
+  name: string;
+  email: string;
+}
+
+interface DesktopApiRequest {
+  path: string;
+  method: "GET" | "POST";
+  body?: string;
+}
+
+interface DesktopApiResponse {
+  status: number;
+  contentType: string | null;
+  body: string;
+}
+
+interface Window {
+  frockbotDesktop?: {
+    request(request: DesktopApiRequest): Promise<DesktopApiResponse>;
+  };
+  getUser(): Promise<DesktopAuthUser | null>;
+  requestAuth(options?: { provider?: string }): Promise<void>;
+  onAuthenticated(callback: (user: DesktopAuthUser) => unknown): () => void;
+  onUserUpdated(
+    callback: (user: DesktopAuthUser | null) => unknown,
+  ): () => void;
+  onAuthError(callback: (context: { message?: string }) => unknown): () => void;
+  signOut(): Promise<void>;
+}
+
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<
+    Record<string, never>,
+    Record<string, never>,
+    unknown
+  >;
+  export default component;
+}

package/src/index.ts

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

package/src/manifest.ts

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

package/src/shared.ts

@@ -0,0 +1,122 @@
+import type { InjectionKey, Ref } from "vue";
+
+export interface AuthenticatedUserV1 {
+  id: string;
+  name: string;
+  email: string;
+  isAdmin: boolean;
+}
+
+export type AuthSessionProjectionV1 =
+  | { schemaVersion: 1; status: "loading" }
+  | { schemaVersion: 1; status: "anonymous" }
+  | {
+      schemaVersion: 1;
+      status: "authenticated";
+      mode: "better-auth" | "desktop" | "development";
+      user: AuthenticatedUserV1;
+    };
+
+export interface AuthSessionClient {
+  readonly projection: Readonly<Ref<AuthSessionProjectionV1>>;
+  readonly signingOut: Readonly<Ref<boolean>>;
+  refresh(): Promise<void>;
+  signOut(): Promise<void>;
+}
+
+export const authSessionClientKey: InjectionKey<AuthSessionClient> = Symbol(
+  "frockbot.auth-session-client",
+);
+
+function record(value: unknown, label: string): Record<PropertyKey, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<PropertyKey, unknown>;
+}
+
+function exactKeys(
+  value: Record<PropertyKey, unknown>,
+  expected: readonly string[],
+  label: string,
+): void {
+  const keys = Reflect.ownKeys(value);
+  if (
+    keys.length !== expected.length ||
+    !keys.every((key) => typeof key === "string" && expected.includes(key))
+  ) {
+    throw new Error(`${label} has unknown fields`);
+  }
+}
+
+function stringField(
+  value: Record<PropertyKey, unknown>,
+  key: string,
+  label: string,
+): string {
+  const field = value[key];
+  if (typeof field !== "string") throw new Error(`${label}.${key} is invalid`);
+  return field;
+}
+
+function booleanField(
+  value: Record<PropertyKey, unknown>,
+  key: string,
+  label: string,
+): boolean {
+  const field = value[key];
+  if (typeof field !== "boolean") {
+    throw new Error(`${label}.${key} is invalid`);
+  }
+  return field;
+}
+
+/** Strictly decodes the auth-owned projection exposed to client Plugins. */
+export function decodeAuthSessionProjectionV1(
+  input: unknown,
+): Exclude<AuthSessionProjectionV1, { status: "loading" }> {
+  const projection = record(input, "auth session projection");
+  if (projection.schemaVersion !== 1) {
+    throw new Error("auth session projection.schemaVersion is invalid");
+  }
+  if (projection.status === "anonymous") {
+    exactKeys(
+      projection,
+      ["schemaVersion", "status"],
+      "auth session projection",
+    );
+    return { schemaVersion: 1, status: "anonymous" };
+  }
+  if (projection.status !== "authenticated") {
+    throw new Error("auth session projection.status is invalid");
+  }
+  exactKeys(
+    projection,
+    ["schemaVersion", "status", "mode", "user"],
+    "auth session projection",
+  );
+  if (
+    projection.mode !== "better-auth" &&
+    projection.mode !== "desktop" &&
+    projection.mode !== "development"
+  ) {
+    throw new Error("auth session projection.mode is invalid");
+  }
+  const user = record(projection.user, "auth session projection.user");
+  exactKeys(
+    user,
+    ["id", "name", "email", "isAdmin"],
+    "auth session projection.user",
+  );
+  return {
+    schemaVersion: 1,
+    status: "authenticated",
+    mode: projection.mode,
+    user: {
+      id: stringField(user, "id", "auth session projection.user"),
+      name: stringField(user, "name", "auth session projection.user"),
+      email: stringField(user, "email", "auth session projection.user"),
+      isAdmin: booleanField(user, "isAdmin", "auth session projection.user"),
+    },
+  };
+}

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", "node", "vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue"]
+}

package/README.md

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