create-handover 0.1.1

package/template/lib/handover.integration.test.ts

@@ -0,0 +1,322 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+
+import { Handover, HandoverError } from "./handover";
+
+function mockJsonResponse(status: number, payload: unknown): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+    },
+  });
+}
+
+test("login + session integration contract", async () => {
+  const originalFetch = globalThis.fetch;
+  const calls: Array<{ url: string; method: string }> = [];
+
+  globalThis.fetch = (async (url: URL | RequestInfo, init?: RequestInit) => {
+    const path = typeof url === "string" ? url : String(url);
+    calls.push({ url: path, method: init?.method ?? "GET" });
+
+    if (path.endsWith("/admin/login")) {
+      return mockJsonResponse(200, {
+        token: "session-token",
+        user: { id: "u1", username: "owner", role: "owner", status: "active" },
+      });
+    }
+
+    if (path.endsWith("/admin/session")) {
+      return mockJsonResponse(200, {
+        isValid: true,
+        user: { id: "u1", username: "owner", role: "owner", status: "active" },
+      });
+    }
+
+    return mockJsonResponse(404, { error: "not found" });
+  }) as typeof fetch;
+
+  try {
+    const sdk = new Handover({ apiKey: "ho_live_test", url: "https://example.com" });
+    const loginResult = await sdk.loginAdmin("owner", "Password123");
+    assert.equal(loginResult.token, "session-token");
+
+    const session = await sdk.getAdminSession("session-token");
+    assert.equal(session.isValid, true);
+    assert.equal(session.user?.username, "owner");
+
+    assert.equal(calls.some((c) => c.url.endsWith("/admin/login") && c.method === "POST"), true);
+    assert.equal(calls.some((c) => c.url.endsWith("/admin/session") && c.method === "POST"), true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("logout and protected routes reject invalid session", async () => {
+  const originalFetch = globalThis.fetch;
+
+  globalThis.fetch = (async () => {
+    return mockJsonResponse(401, { error: "Unauthorized" });
+  }) as typeof fetch;
+
+  try {
+    const sdk = new Handover({ apiKey: "ho_live_test", url: "https://example.com" });
+
+    await assert.rejects(() => sdk.logoutAdmin("bad-session"), (err: unknown) => {
+      return err instanceof HandoverError && err.code === "UNAUTHORIZED";
+    });
+
+    await assert.rejects(() => sdk.updateText("hero_title", "New", "bad-session"), (err: unknown) => {
+      return err instanceof HandoverError && err.code === "UNAUTHORIZED";
+    });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("role-based authorization returns FORBIDDEN for user management", async () => {
+  const originalFetch = globalThis.fetch;
+
+  globalThis.fetch = (async () => {
+    return mockJsonResponse(403, { error: "Forbidden" });
+  }) as typeof fetch;
+
+  try {
+    const sdk = new Handover({ apiKey: "ho_live_test", url: "https://example.com" });
+
+    await assert.rejects(
+      () => sdk.updateAdminUser("session", { userId: "u2", role: "owner" }),
+      (err: unknown) => err instanceof HandoverError && err.code === "FORBIDDEN",
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("legacy public content flow still works via POST /content", async () => {
+  const originalFetch = globalThis.fetch;
+  const calls: Array<{ url: string; method: string; headers?: HeadersInit }> = [];
+
+  globalThis.fetch = (async (url: URL | RequestInfo, init?: RequestInit) => {
+    const path = typeof url === "string" ? url : String(url);
+    calls.push({ url: path, method: init?.method ?? "GET", headers: init?.headers });
+
+    if (path.endsWith("/content") && init?.method === "POST") {
+      return mockJsonResponse(200, {
+        text: { hero_title: "Hello" },
+        images: [],
+      });
+    }
+
+    return mockJsonResponse(404, { error: "not found" });
+  }) as typeof fetch;
+
+  try {
+    const sdk = new Handover({ apiKey: "ho_live_test", url: "https://example.com" });
+    const content = await sdk.getContent();
+
+    assert.equal(content.text.hero_title, "Hello");
+    assert.equal(Array.isArray(content.images), true);
+    assert.equal(calls.some((c) => c.url.includes("?apiKey=")), false);
+    assert.equal(calls.some((c) => c.url.endsWith("/content") && c.method === "POST"), true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("legacy content fallback uses GET /content without leaking apiKey query", async () => {
+  const originalFetch = globalThis.fetch;
+  const calls: Array<{ url: string; method: string }> = [];
+
+  globalThis.fetch = (async (url: URL | RequestInfo, init?: RequestInit) => {
+    const path = typeof url === "string" ? url : String(url);
+    const method = init?.method ?? "GET";
+    calls.push({ url: path, method });
+
+    if (path.endsWith("/content") && method === "POST") {
+      return mockJsonResponse(405, { error: "method not allowed" });
+    }
+
+    if (path.endsWith("/content") && method === "GET") {
+      return mockJsonResponse(200, {
+        text: { fallback_title: "Legacy" },
+        images: [],
+      });
+    }
+
+    return mockJsonResponse(404, { error: "not found" });
+  }) as typeof fetch;
+
+  try {
+    const sdk = new Handover({ apiKey: "ho_live_test", url: "https://example.com" });
+    const content = await sdk.getContent();
+
+    assert.equal(content.text.fallback_title, "Legacy");
+    assert.equal(calls.some((c) => c.method === "POST" && c.url.endsWith("/content")), true);
+    assert.equal(calls.some((c) => c.method === "GET" && c.url.endsWith("/content")), true);
+    assert.equal(calls.some((c) => c.url.includes("?apiKey=")), false);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("legacy verifyPassword flow remains backward-compatible", async () => {
+  const originalFetch = globalThis.fetch;
+  let callCount = 0;
+
+  globalThis.fetch = (async () => {
+    callCount += 1;
+    if (callCount === 1) {
+      return mockJsonResponse(401, { error: "invalid password" });
+    }
+    return mockJsonResponse(200, { isValid: true });
+  }) as typeof fetch;
+
+  try {
+    const sdk = new Handover({ apiKey: "ho_live_test", url: "https://example.com" });
+    const first = await sdk.verifyPassword("wrong");
+    const second = await sdk.verifyPassword("right");
+
+    assert.equal(first, false);
+    assert.equal(second, true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("user management CRUD flow works for admin role", async () => {
+  const originalFetch = globalThis.fetch;
+  const users: Array<{ id: string; username: string; role: string; status: string; lastLoginAt?: number }> = [
+    { id: "u1", username: "owner", role: "owner", status: "active" },
+  ];
+
+  globalThis.fetch = (async (url: URL | RequestInfo, init?: RequestInit) => {
+    const path = typeof url === "string" ? url : String(url);
+    const body = init?.body ? JSON.parse(String(init.body)) : {};
+
+    if (path.endsWith("/admin/users") && init?.method === "POST") {
+      return mockJsonResponse(200, users);
+    }
+
+    if (path.endsWith("/admin/users/create") && init?.method === "POST") {
+      const created = {
+        id: `u${users.length + 1}`,
+        username: body.username,
+        role: body.role,
+        status: "active",
+      };
+      users.push(created);
+      return mockJsonResponse(200, created);
+    }
+
+    if (path.endsWith("/admin/users/update") && init?.method === "POST") {
+      const user = users.find((u) => u.id === body.userId);
+      if (!user) {
+        return mockJsonResponse(404, { error: "User not found" });
+      }
+      if (body.status) {
+        user.status = body.status;
+      }
+      if (body.role) {
+        user.role = body.role;
+      }
+      return mockJsonResponse(200, { success: true });
+    }
+
+    if (path.endsWith("/admin/users/delete") && init?.method === "POST") {
+      const index = users.findIndex((u) => u.id === body.userId);
+      if (index === -1) {
+        return mockJsonResponse(404, { error: "User not found" });
+      }
+      if (users[index].role === "owner") {
+        return mockJsonResponse(409, { error: "Owner account cannot be deleted" });
+      }
+      users.splice(index, 1);
+      return mockJsonResponse(200, { success: true });
+    }
+
+    return mockJsonResponse(404, { error: "not found" });
+  }) as typeof fetch;
+
+  try {
+    const sdk = new Handover({ apiKey: "ho_live_test", url: "https://example.com" });
+
+    const created = await sdk.createAdminUser("admin-session", {
+      username: "editor",
+      password: "Password123",
+      role: "editor",
+    });
+    assert.equal(created.username, "editor");
+
+    let listed = await sdk.listAdminUsers("admin-session");
+    assert.equal(listed.length, 2);
+
+    await sdk.updateAdminUser("admin-session", {
+      userId: created.id,
+      status: "disabled",
+    });
+
+    listed = await sdk.listAdminUsers("admin-session");
+    assert.equal(listed.find((u) => u.id === created.id)?.status, "disabled");
+
+    await sdk.deleteAdminUser("admin-session", created.id);
+    listed = await sdk.listAdminUsers("admin-session");
+    assert.equal(listed.some((u) => u.id === created.id), false);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("role-guarded user management actions reject editor role", async () => {
+  const originalFetch = globalThis.fetch;
+
+  globalThis.fetch = (async () => {
+    return mockJsonResponse(403, { error: "Forbidden" });
+  }) as typeof fetch;
+
+  try {
+    const sdk = new Handover({ apiKey: "ho_live_test", url: "https://example.com" });
+
+    await assert.rejects(
+      () => sdk.createAdminUser("editor-session", { username: "x", password: "Password123", role: "viewer" }),
+      (err: unknown) => err instanceof HandoverError && err.code === "FORBIDDEN",
+    );
+
+    await assert.rejects(
+      () => sdk.deleteAdminUser("editor-session", "u2"),
+      (err: unknown) => err instanceof HandoverError && err.code === "FORBIDDEN",
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("kill switch blocks write operations with HANDOVER_LOCKED", async () => {
+  const originalFetch = globalThis.fetch;
+
+  globalThis.fetch = (async () => {
+    return mockJsonResponse(402, { error: "HANDOVER_LOCKED" });
+  }) as typeof fetch;
+
+  try {
+    const sdk = new Handover({ apiKey: "ho_live_test", url: "https://example.com" });
+
+    await assert.rejects(
+      () => sdk.updateText("hero_title", "blocked", "session-token"),
+      (err: unknown) => err instanceof HandoverError && err.code === "HANDOVER_LOCKED",
+    );
+
+    await assert.rejects(
+      () => sdk.deleteText("hero_title", "session-token"),
+      (err: unknown) => err instanceof HandoverError && err.code === "HANDOVER_LOCKED",
+    );
+
+    await assert.rejects(
+      () => sdk.deleteImage("img_1", "session-token"),
+      (err: unknown) => err instanceof HandoverError && err.code === "HANDOVER_LOCKED",
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

package/template/lib/handover.ts

@@ -0,0 +1,389 @@
+const API_KEY_HEADER = "X-Handover-Api-Key";
+const ADMIN_SESSION_HEADER = "X-Handover-Admin-Session";
+
+export class HandoverError extends Error {
+    readonly code: string;
+
+    constructor(code: string) {
+        super(code);
+        this.name = "HandoverError";
+        this.code = code;
+    }
+}
+
+export class Handover {
+    private url: string;
+    private apiKey: string;
+
+    constructor(config: { apiKey: string, url: string }) {
+        this.apiKey = config.apiKey.trim();
+        this.url = config.url.replace(/\/$/, "");
+    }
+
+    private jsonHeaders() {
+        return {
+            "Content-Type": "application/json",
+            [API_KEY_HEADER]: this.apiKey,
+        };
+    }
+
+    private adminHeaders(sessionToken: string) {
+        return {
+            ...this.jsonHeaders(),
+            [ADMIN_SESSION_HEADER]: sessionToken,
+        };
+    }
+
+    private async throwForError(res: Response, fallbackCode: string) {
+        if (res.status === 402) {
+            throw new HandoverError("HANDOVER_LOCKED");
+        }
+
+        if (res.status === 401) {
+            throw new HandoverError("UNAUTHORIZED");
+        }
+
+        if (res.status === 413) {
+            throw new HandoverError("STORAGE_LIMIT_EXCEEDED");
+        }
+
+        if (res.status === 415) {
+            throw new HandoverError("INVALID_IMAGE_TYPE");
+        }
+
+        if (res.status === 429) {
+            throw new HandoverError("AUTH_RATE_LIMITED");
+        }
+
+        if (res.status === 403) {
+            throw new HandoverError("FORBIDDEN");
+        }
+
+        if (res.status === 412) {
+            throw new HandoverError("ADMIN_NOT_BOOTSTRAPPED");
+        }
+
+        throw new HandoverError(fallbackCode);
+    }
+
+    async getContent(): Promise<{ text: Record<string, unknown>, images: Array<{ _id: string, url: string, altText?: string, mimeType: string }> }> {
+        const preferred = await fetch(`${this.url}/content`, {
+            method: "POST",
+            headers: this.jsonHeaders(),
+            body: "{}",
+            cache: "no-store",
+        });
+
+        if (preferred.ok) {
+            return await preferred.json();
+        }
+
+        if (preferred.status !== 404 && preferred.status !== 405) {
+            await this.throwForError(preferred, "FAILED_TO_FETCH_CONTENT");
+        }
+
+        const fallback = await fetch(`${this.url}/content`, {
+            method: "GET",
+            headers: this.jsonHeaders(),
+            cache: "no-store",
+        });
+
+        if (!fallback.ok) {
+            await this.throwForError(fallback, "FAILED_TO_FETCH_CONTENT");
+        }
+
+        return await fallback.json();
+    }
+
+    async deleteImage(imageId: string, sessionToken: string): Promise<boolean> {
+        const res = await fetch(`${this.url}/storage/delete`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: JSON.stringify({ imageId }),
+        });
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_DELETE_IMAGE");
+        }
+
+        return true;
+    }
+
+    async updateText(key: string, value: unknown, sessionToken: string): Promise<boolean> {
+        const res = await fetch(`${this.url}/update_content`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: JSON.stringify({ key, value }),
+        });
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_UPDATE_CONTENT");
+        }
+
+        return true;
+    }
+
+    async deleteText(key: string, sessionToken: string): Promise<boolean> {
+        const res = await fetch(`${this.url}/content/delete_key`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: JSON.stringify({ key }),
+        });
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_DELETE_CONTENT");
+        }
+
+        return true;
+    }
+
+    async verifyPassword(password: string): Promise<boolean> {
+        const res = await fetch(`${this.url}/verify`, {
+            method: "POST",
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ password }),
+        });
+
+        if (res.status === 401) {
+            return false;
+        }
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_VERIFY_PASSWORD");
+        }
+
+        const data = await res.json();
+        return data.isValid;
+    }
+
+    async bootstrapAdmin(clientPassword: string, username: string, password: string): Promise<{ token: string; user: { id: string; username: string; role: string; status: string } }> {
+        const res = await fetch(`${this.url}/admin/bootstrap`, {
+            method: "POST",
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ clientPassword, username, password }),
+        });
+
+        if (res.status === 401) {
+            throw new HandoverError("INVALID_PASSWORD");
+        }
+
+        if (res.status === 409) {
+            throw new HandoverError("ADMIN_USERS_ALREADY_INITIALIZED");
+        }
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_BOOTSTRAP_ADMIN");
+        }
+
+        return await res.json();
+    }
+
+    async loginAdmin(username: string, password: string): Promise<{ token: string; user: { id: string; username: string; role: string; status: string } }> {
+        const res = await fetch(`${this.url}/admin/login`, {
+            method: "POST",
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ username, password }),
+        });
+
+        if (res.status === 401) {
+            throw new HandoverError("INVALID_CREDENTIALS");
+        }
+
+        if (res.status === 423) {
+            throw new HandoverError("ACCOUNT_DISABLED");
+        }
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_LOGIN");
+        }
+
+        return await res.json();
+    }
+
+    async logoutAdmin(sessionToken: string): Promise<boolean> {
+        const res = await fetch(`${this.url}/admin/logout`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: "{}",
+        });
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_LOGOUT");
+        }
+
+        return true;
+    }
+
+    async getAdminSession(sessionToken: string): Promise<{ isValid: boolean; user?: { id: string; username: string; role: string; status: string } }> {
+        const res = await fetch(`${this.url}/admin/session`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: "{}",
+        });
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_GET_SESSION");
+        }
+
+        return await res.json();
+    }
+
+    async listAdminUsers(sessionToken: string): Promise<Array<{ id: string; username: string; role: string; status: string; lastLoginAt?: number }>> {
+        const res = await fetch(`${this.url}/admin/users`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: "{}",
+        });
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_LIST_USERS");
+        }
+
+        return await res.json();
+    }
+
+    async createAdminUser(sessionToken: string, payload: { username: string; password: string; role: "admin" | "editor" | "viewer" }): Promise<{ id: string; username: string; role: string; status: string }> {
+        const res = await fetch(`${this.url}/admin/users/create`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: JSON.stringify(payload),
+        });
+
+        if (res.status === 409) {
+            throw new HandoverError("USERNAME_TAKEN");
+        }
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_CREATE_USER");
+        }
+
+        return await res.json();
+    }
+
+    async updateAdminUser(sessionToken: string, payload: { userId: string; role?: "owner" | "admin" | "editor" | "viewer"; status?: "active" | "disabled" | "locked" }): Promise<boolean> {
+        const res = await fetch(`${this.url}/admin/users/update`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: JSON.stringify(payload),
+        });
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_UPDATE_USER");
+        }
+
+        return true;
+    }
+
+    async deleteAdminUser(sessionToken: string, userId: string): Promise<boolean> {
+        const res = await fetch(`${this.url}/admin/users/delete`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: JSON.stringify({ userId }),
+        });
+
+        if (res.status === 409) {
+            throw new HandoverError("CANNOT_DELETE_OWNER");
+        }
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_DELETE_USER");
+        }
+
+        return true;
+    }
+
+    async resetAdminUserPassword(sessionToken: string, payload: { userId: string; newPassword: string }): Promise<boolean> {
+        const res = await fetch(`${this.url}/admin/users/reset_password`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: JSON.stringify(payload),
+        });
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_RESET_USER_PASSWORD");
+        }
+
+        return true;
+    }
+
+    async createAdminUserResetToken(sessionToken: string, userId: string): Promise<{ token: string; expiresAt: number }> {
+        const res = await fetch(`${this.url}/admin/users/create_reset_token`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: JSON.stringify({ userId }),
+        });
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_CREATE_RESET_TOKEN");
+        }
+
+        return await res.json();
+    }
+
+    async resetAdminPasswordWithToken(resetToken: string, newPassword: string): Promise<boolean> {
+        const res = await fetch(`${this.url}/admin/reset_with_token`, {
+            method: "POST",
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ resetToken, newPassword }),
+        });
+
+        if (res.status === 410) {
+            throw new HandoverError("RESET_TOKEN_EXPIRED");
+        }
+
+        if (res.status === 409) {
+            throw new HandoverError("RESET_TOKEN_USED");
+        }
+
+        if (res.status === 400) {
+            throw new HandoverError("INVALID_RESET_TOKEN");
+        }
+
+        if (!res.ok) {
+            await this.throwForError(res, "FAILED_TO_RESET_WITH_TOKEN");
+        }
+
+        return true;
+    }
+
+    async uploadImage(file: File, sessionToken: string, altText?: string): Promise<{ imageId: string, url: string }> {
+        const urlRes = await fetch(`${this.url}/storage/upload_url`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: "{}",
+        });
+
+        if (!urlRes.ok) {
+            await this.throwForError(urlRes, "FAILED_TO_GET_UPLOAD_URL");
+        }
+
+        const { url: uploadUrl } = await urlRes.json();
+
+        const uploadRes = await fetch(uploadUrl, {
+            method: "POST",
+            headers: { "Content-Type": file.type },
+            body: file,
+        });
+
+        if (!uploadRes.ok) {
+            throw new HandoverError("FAILED_TO_UPLOAD_FILE");
+        }
+
+        const { storageId } = await uploadRes.json();
+
+        const saveRes = await fetch(`${this.url}/storage/save`, {
+            method: "POST",
+            headers: this.adminHeaders(sessionToken),
+            body: JSON.stringify({
+                storageId,
+                altText,
+            }),
+        });
+
+        if (!saveRes.ok) {
+            await this.throwForError(saveRes, "FAILED_TO_SAVE_IMAGE");
+        }
+
+        return await saveRes.json();
+    }
+}