Xu_BrowserBookmark/openspec/specs/api/spec.md

Capability: API (OpenAPI-backed)

Purpose

Describe the core HTTP API behavior and constraints. The OpenAPI 3.1 contract lives in spec/openapi.yaml.

Requirements

Requirement: Health check

The system SHALL expose a health endpoint for availability checks.

Scenario: Health endpoint returns OK

• WHEN a client calls GET /health
• THEN the server returns 200

Requirement: Authentication

The system SHALL support email+password registration and login.

Scenario: Register then login

• WHEN a user registers with a valid email and password
• THEN the server returns a JWT token
• WHEN the user logs in with the same credentials
• THEN the server returns a JWT token

Requirement: Public bookmarks visibility

The system SHALL allow anonymous users to view public bookmarks.

Scenario: List public bookmarks without auth

• WHEN a client calls GET /bookmarks/public without a token
• THEN the server returns 200 and a list of bookmarks

Requirement: Private bookmarks visibility

The system SHALL restrict private bookmark data to authenticated users.

Scenario: List my bookmarks requires auth

• WHEN a client calls GET /bookmarks without a token
• THEN the server returns an auth error
• WHEN a client calls GET /bookmarks with a valid token
• THEN the server returns 200 and the user's bookmarks

Requirement: Sync (LWW)

The system SHALL support last-write-wins (LWW) synchronization for folders and bookmarks.

Scenario: Push local changes then pull

• WHEN an authenticated client calls POST /sync/push with folders/bookmarks
• THEN the server stores the items using LWW semantics
• WHEN the client calls GET /sync/pull
• THEN the server returns folders/bookmarks and serverTime

Requirement: Admin user management (email-based)

The system SHALL treat exactly one configured email as an administrator and allow that user to manage/view users.

Scenario: Non-admin cannot access admin APIs

• GIVEN an authenticated user whose email is not equal to ADMIN_EMAIL
• WHEN the user calls GET /admin/users
• THEN the server returns a 403 error

Scenario: Admin can list users

• GIVEN an authenticated user whose email equals ADMIN_EMAIL
• WHEN the user calls GET /admin/users
• THEN the server returns 200 and a list of users

Scenario: Admin can view a user's bookmarks

• GIVEN an authenticated admin user
• WHEN the admin calls GET /admin/users/{id}/bookmarks
• THEN the server returns 200 and that user's bookmarks

Requirement: Credential storage API

The system SHALL provide authenticated CRUD APIs for credentials scoped to the current user.

Scenario: Create credential

• WHEN an authenticated user calls POST /credentials with siteOrigin, username, and password
• THEN the server stores the credential and returns the created record

Scenario: List credentials

• WHEN an authenticated user calls GET /credentials?siteOrigin=...
• THEN the server returns the matching credentials for that user

Scenario: Update credential

• WHEN an authenticated user calls PATCH /credentials/{id}
• THEN the server updates the credential and returns the updated record

Scenario: Delete credential

• WHEN an authenticated user calls DELETE /credentials/{id}
• THEN the server deletes the credential

Requirement: Credential plaintext access

The system SHALL allow authenticated users to request plaintext passwords for their own credentials.

Scenario: User requests plaintext

• GIVEN an authenticated user
• WHEN the user calls GET /credentials?includePassword=true
• THEN the server returns plaintext passwords for that user

Scenario: Admin requests plaintext for a user

• GIVEN an authenticated admin user
• WHEN the admin calls GET /admin/users/{id}/credentials?includePassword=true
• THEN the server returns plaintext passwords for that user

Requirement: Admin credential management

The system SHALL allow an admin to list and manage any user’s credentials.

Scenario: Admin lists user credentials

• GIVEN an authenticated admin user
• WHEN the admin calls GET /admin/users/{id}/credentials
• THEN the server returns that user’s credentials