admin/_docs/02_document/tests/blackbox-tests.md

Blackbox Tests

Positive Scenarios

FT-P-01: Successful Login

Summary: User with valid credentials receives a JWT token. Traces to: AC-1 Category: Authentication

Preconditions:

• Seed user admin@azaion.com exists in database

Input data: Valid email/password for seed admin user

Steps:

Step	Consumer Action	Expected System Response
1	POST /login with valid email and password	HTTP 200, body contains non-empty token string

Expected outcome: HTTP 200 with JWT token in response body Max execution time: 5s

---

FT-P-02: Successful User Registration

Summary: ApiAdmin creates a new user account. Traces to: AC-5, AC-6, AC-7 Category: User Management

Preconditions:

• Caller authenticated as ApiAdmin

Input data: {"email":"newuser@test.com","password":"validpwd1","role":"Operator"}

Steps:

Step	Consumer Action	Expected System Response
1	Login as admin to get JWT	HTTP 200, JWT token
2	POST /users with valid registration data and ApiAdmin JWT	HTTP 200

Expected outcome: HTTP 200, user created Max execution time: 5s

---

FT-P-03: JWT Token Structure Validation

Summary: JWT token contains correct issuer, audience, and lifetime claims. Traces to: AC-4 Category: Authentication

Preconditions:

• Valid login completed

Input data: JWT token from login response

Steps:

Step	Consumer Action	Expected System Response
1	Login to get JWT	HTTP 200, JWT token
2	Decode JWT payload (Base64)	Claims contain iss, aud, exp
3	Validate iss == "AzaionApi"	Match
4	Validate aud == "Annotators/OrangePi/Admins"	Match
5	Validate exp - iat ≈ 14400s (4 hours)	Within ± 60s

Expected outcome: All JWT claims match expected values Max execution time: 5s

---

FT-P-04: First Hardware Check Stores Fingerprint

Summary: On first hardware check, the fingerprint is stored for the user. Traces to: AC-10 Category: Hardware Binding

Preconditions:

• User exists with no hardware bound

Input data: {"hardware":"test-hw-fingerprint-001"}

Steps:

Step	Consumer Action	Expected System Response
1	Register new user, login to get JWT	HTTP 200
2	POST /resources/check with hardware string	HTTP 200, body true

Expected outcome: HTTP 200, hardware stored Max execution time: 5s

---

FT-P-05: Subsequent Hardware Check Matches

Summary: Same hardware fingerprint passes validation on subsequent calls. Traces to: AC-11 Category: Hardware Binding

Preconditions:

• User with hardware already bound (from FT-P-04)

Input data: Same hardware string as initial binding

Steps:

Step	Consumer Action	Expected System Response
1	POST /resources/check with same hardware	HTTP 200, body true

Expected outcome: HTTP 200 Max execution time: 5s

---

FT-P-06: List All Users

Summary: ApiAdmin retrieves the user list. Traces to: AC-9 Category: User Management

Preconditions:

• Caller authenticated as ApiAdmin

Input data: GET /users with ApiAdmin JWT

Steps:

Step	Consumer Action	Expected System Response
1	GET /users with ApiAdmin JWT	HTTP 200, JSON array with >= 1 user

Expected outcome: HTTP 200, array containing at least seed users Max execution time: 5s

---

FT-P-07: Filter Users by Email

Summary: ApiAdmin filters users by email substring. Traces to: AC-9 Category: User Management

Preconditions:

• Caller authenticated as ApiAdmin, seed users exist

Input data: GET /users?email=admin

Steps:

Step	Consumer Action	Expected System Response
1	GET /users?email=admin with ApiAdmin JWT	HTTP 200, all returned emails contain "admin"

Expected outcome: HTTP 200, filtered list Max execution time: 5s

---

FT-P-08: Upload Resource File

Summary: Authenticated user uploads a file to a resource folder. Traces to: AC-13 Category: Resource Distribution

Preconditions:

• Caller authenticated

Input data: Multipart form upload with 1 KB text file

Steps:

Step	Consumer Action	Expected System Response
1	POST /resources/testfolder with multipart file	HTTP 200

Expected outcome: HTTP 200, file stored Max execution time: 5s

---

FT-P-09: Download Encrypted Resource

Summary: Authenticated user downloads an encrypted resource file. Traces to: AC-14, AC-18 Category: Resource Distribution

Preconditions:

• User authenticated, hardware bound, resource file uploaded

Input data: {"password":"validpwd1","hardware":"test-hw-001","fileName":"test.txt"}

Steps:

Step	Consumer Action	Expected System Response
1	POST /resources/get with credentials	HTTP 200, Content-Type: application/octet-stream, non-empty body

Expected outcome: HTTP 200 with encrypted binary content Max execution time: 10s

---

FT-P-10: Encryption Round-Trip Verification

Summary: Downloaded encrypted resource decrypts to original file content. Traces to: AC-15, AC-19 Category: Resource Distribution

Preconditions:

• Known file uploaded, user credentials known

Input data: Original file content, user email, password, hardware hash

Steps:

Step	Consumer Action	Expected System Response
1	Upload known file	HTTP 200
2	Download encrypted file via API	HTTP 200, encrypted bytes
3	Derive AES key from email + password + hwHash	Key bytes
4	Decrypt downloaded content with derived key	Decrypted bytes
5	Compare decrypted bytes with original	Byte-level equality

Expected outcome: Decrypted content matches original file exactly Max execution time: 10s

---

FT-P-11: Change User Role

Summary: ApiAdmin changes a user's role. Traces to: AC-9 Category: User Management

Preconditions:

• Target user exists, caller is ApiAdmin

Input data: {"email":"testuser@test.com","role":"Admin"}

Steps:

Step	Consumer Action	Expected System Response
1	PUT /users/role with ApiAdmin JWT	HTTP 200

Expected outcome: HTTP 200, role updated Max execution time: 5s

---

FT-P-12: Disable User Account

Summary: ApiAdmin disables a user account. Traces to: AC-9 Category: User Management

Preconditions:

• Target user exists, caller is ApiAdmin

Input data: {"email":"testuser@test.com","isEnabled":false}

Steps:

Step	Consumer Action	Expected System Response
1	PUT /users/enable with ApiAdmin JWT	HTTP 200

Expected outcome: HTTP 200, account disabled Max execution time: 5s

---

FT-P-13: Delete User

Summary: ApiAdmin deletes a user account. Traces to: AC-9 Category: User Management

Preconditions:

• Target user exists, caller is ApiAdmin

Input data: DELETE /users?email=testuser@test.com

Steps:

Step	Consumer Action	Expected System Response
1	DELETE /users?email=testuser@test.com with ApiAdmin JWT	HTTP 200

Expected outcome: HTTP 200, user deleted Max execution time: 5s

---

Negative Scenarios

FT-N-01: Login with Unknown Email

Summary: Login attempt with non-existent email returns appropriate error. Traces to: AC-2 Category: Authentication

Preconditions:

• Email does not exist in database

Input data: {"email":"nonexistent@test.com","password":"anypass1"}

Steps:

Step	Consumer Action	Expected System Response
1	POST /login with unknown email	HTTP 409, ExceptionEnum code 10 (NoEmailFound)

Expected outcome: HTTP 409 with error code 10 Max execution time: 5s

---

FT-N-02: Login with Wrong Password

Summary: Login attempt with correct email but wrong password returns error. Traces to: AC-3 Category: Authentication

Preconditions:

• User exists in database

Input data: {"email":"admin@azaion.com","password":"wrongpassword123"}

Steps:

Step	Consumer Action	Expected System Response
1	POST /login with wrong password	HTTP 409, ExceptionEnum code 30 (WrongPassword)

Expected outcome: HTTP 409 with error code 30 Max execution time: 5s

---

FT-N-03: Register with Short Email

Summary: Registration with email shorter than 8 characters is rejected. Traces to: AC-5 Category: User Management

Preconditions:

• Caller authenticated as ApiAdmin

Input data: {"email":"short","password":"validpwd1","role":"Operator"}

Steps:

Step	Consumer Action	Expected System Response
1	POST /users with short email	HTTP 400, validation error

Expected outcome: HTTP 400 with email length validation error Max execution time: 5s

---

FT-N-04: Register with Invalid Email Format

Summary: Registration with invalid email format (>= 8 chars but not email) is rejected. Traces to: AC-6 Category: User Management

Preconditions:

• Caller authenticated as ApiAdmin

Input data: {"email":"notanemail","password":"validpwd1","role":"Operator"}

Steps:

Step	Consumer Action	Expected System Response
1	POST /users with invalid email format	HTTP 400, validation error

Expected outcome: HTTP 400 with email format validation error Max execution time: 5s

---

FT-N-05: Upload Empty File

Summary: Upload request with no file attached returns error. Traces to: AC-16 Category: Resource Distribution

Preconditions:

• Caller authenticated

Input data: POST /resources/testfolder with no file

Steps:

Step	Consumer Action	Expected System Response
1	POST /resources/testfolder with empty request	HTTP 409, ExceptionEnum code 70 (NoFileProvided)

Expected outcome: HTTP 409 with error code 70 Max execution time: 5s

---

FT-N-06: Hardware Mismatch

Summary: Hardware check with different fingerprint after binding returns error. Traces to: AC-12 Category: Hardware Binding

Preconditions:

• User has hardware already bound to a different fingerprint

Input data: {"hardware":"different-hardware-xyz"}

Steps:

Step	Consumer Action	Expected System Response
1	POST /resources/check with different hardware	HTTP 409, ExceptionEnum code 40 (HardwareIdMismatch)

Expected outcome: HTTP 409 with error code 40 Max execution time: 5s

---

FT-N-07: Register Duplicate Email

Summary: Registration with already-existing email returns error. Traces to: AC-8 Category: User Management

Preconditions:

• User with target email already exists

Input data: {"email":"admin@azaion.com","password":"validpwd1","role":"Operator"}

Steps:

Step	Consumer Action	Expected System Response
1	POST /users with existing email	HTTP 409, ExceptionEnum code 20 (EmailExists)

Expected outcome: HTTP 409 with error code 20 Max execution time: 5s

---

FT-N-08: Register with Short Password

Summary: Registration with password shorter than 8 characters is rejected. Traces to: AC-7 Category: User Management

Preconditions:

• Caller authenticated as ApiAdmin

Input data: {"email":"newuser@test.com","password":"short","role":"Operator"}

Steps:

Step	Consumer Action	Expected System Response
1	POST /users with short password	HTTP 400, validation error

Expected outcome: HTTP 400 with password length validation error Max execution time: 5s

---

Cycle 1 Additions (2026-05-13)

The scenarios below were appended during the existing-code cycle 1 Test-Spec Sync (autodev Step 12) for tasks AZ-513, AZ-196, AZ-183, AZ-197. Numbering continues from the legacy IDs above; existing IDs are preserved.

Cycle 1 Obsoletion Note

The following legacy entries describe behaviour removed by AZ-197 (admin-side hardware-binding cleanup). Their bodies are intentionally left intact to preserve traceability IDs per the cycle-update rule "preserve existing traceability IDs"; they should be treated as obsolete and superseded by FT-N-15 below:

• FT-P-04 (First Hardware Check Stores Fingerprint) — superseded; the POST /resources/check endpoint and the hardware-store side-effect were removed.
• FT-P-05 (Subsequent Hardware Check Matches) — superseded; same endpoint removed.
• FT-N-06 (Hardware Mismatch) — superseded; the HardwareIdMismatch / error code 40 path no longer exists in ExceptionEnum.
• FT-P-09 / FT-P-10 wire shape — the hardware field on POST /resources/get/{dataFolder} is no longer required; the encryption key is now derived from email + password only. The tests still pass without the field; do not regenerate spec bodies until a full /test-spec rerun.

See _docs/03_implementation/batch_06_report.md for the full AZ-197 implementation rationale and the wire-compat policy decision (drop entirely).

---

Detection Classes CRUD (AZ-513)

FT-P-14: POST /classes Creates Detection Class

Summary: ApiAdmin creates a new detection class and the response includes the assigned id. Traces to: AZ-513 AC-1 Category: Detection Classes CRUD

Preconditions:

• Caller authenticated as ApiAdmin
• detection_classes table exists

Input data: {"name":"Tank","shortName":"T","color":"#FF0000","maxSizeM":5.0}

Steps:

Step	Consumer Action	Expected System Response
1	POST /classes with valid body and ApiAdmin JWT	HTTP 200/201 with body containing assigned id and the submitted fields

Expected outcome: HTTP 200 or 201, response body has integer id and matches input fields Max execution time: 5s

---

FT-P-15: PATCH /classes/{id} Full Body Update

Summary: Updating a detection class with a full body replaces the changed fields. Traces to: AZ-513 AC-3 Category: Detection Classes CRUD

Preconditions:

• A detection class with id 7 exists with name: "Tank"

Input data: {"name":"Heavy Tank","shortName":"T","color":"#FF0000","maxSizeM":5.0} to PATCH /classes/7

Steps:

Step	Consumer Action	Expected System Response
1	PATCH /classes/7 with full body and ApiAdmin JWT	HTTP 200, response body shows name: "Heavy Tank"

Expected outcome: HTTP 200, updated entity reflects the changed field Max execution time: 5s

---

FT-P-16: PATCH /classes/{id} Partial Body Update

Summary: PATCH with only the changed field updates that field and leaves others intact. Traces to: AZ-513 AC-4 Category: Detection Classes CRUD

Preconditions:

• A detection class with id 7 exists with name: "Tank", color: "#FF0000", maxSizeM: 5.0

Input data: {"color":"#00FF00"} to PATCH /classes/7

Steps:

Step	Consumer Action	Expected System Response
1	PATCH /classes/7 with partial body and ApiAdmin JWT	HTTP 200, response body shows color: "#00FF00"; other fields unchanged

Expected outcome: HTTP 200, partial-merge semantics confirmed Max execution time: 5s

---

FT-P-17: DELETE /classes/{id} Removes Class

Summary: ApiAdmin deletes a detection class and it disappears from the DB. Traces to: AZ-513 AC-7 Category: Detection Classes CRUD

Preconditions:

• A detection class with id 7 exists

Input data: DELETE /classes/7

Steps:

Step	Consumer Action	Expected System Response
1	DELETE /classes/7 with ApiAdmin JWT	HTTP 200 or 204
2	GET the class list (or PATCH the same id)	id 7 no longer present

Expected outcome: HTTP 200/204; class removed from DB Max execution time: 5s

---

FT-N-09: POST /classes Without ApiAdmin JWT

Summary: POST /classes requires the same apiAdminPolicy as /users; non-admin / unauthenticated calls are rejected. Traces to: AZ-513 AC-2 Category: Detection Classes CRUD

Preconditions: None (negative path)

Input data: Valid body, but caller has no JWT or a non-ApiAdmin JWT

Steps:

Step	Consumer Action	Expected System Response
1	POST /classes without JWT	HTTP 401
2	POST /classes with non-ApiAdmin JWT	HTTP 403

Expected outcome: HTTP 401 (no JWT) or 403 (non-admin) Max execution time: 5s

---

FT-N-10: PATCH /classes/{id} Unknown id Returns 404

Summary: PATCH against a non-existent id returns 404. Traces to: AZ-513 AC-5 Category: Detection Classes CRUD

Preconditions: No detection class with id 9999

Input data: PATCH /classes/9999 with any valid body

Steps:

Step	Consumer Action	Expected System Response
1	PATCH /classes/9999 with ApiAdmin JWT	HTTP 404

Expected outcome: HTTP 404 Max execution time: 5s

---

FT-N-11: PATCH /classes/{id} Without ApiAdmin JWT

Summary: PATCH /classes/{id} requires apiAdminPolicy. Traces to: AZ-513 AC-6 Category: Detection Classes CRUD

Input data: Any valid body to PATCH /classes/{id}

Steps:

Step	Consumer Action	Expected System Response
1	PATCH /classes/{id} without JWT	HTTP 401
2	PATCH /classes/{id} with non-ApiAdmin JWT	HTTP 403

Expected outcome: HTTP 401 or 403 Max execution time: 5s

---

FT-N-12: DELETE /classes/{id} Unknown id Returns 404

Summary: DELETE against a non-existent id returns 404 (matching /users semantics — non-idempotent). Traces to: AZ-513 AC-8 Category: Detection Classes CRUD

Preconditions: No detection class with id 9999

Input data: DELETE /classes/9999

Steps:

Step	Consumer Action	Expected System Response
1	DELETE /classes/9999 with ApiAdmin JWT	HTTP 404

Expected outcome: HTTP 404 Max execution time: 5s

---

FT-N-13: DELETE /classes/{id} Without ApiAdmin JWT

Summary: DELETE /classes/{id} requires apiAdminPolicy. Traces to: AZ-513 AC-9 Category: Detection Classes CRUD

Input data: DELETE /classes/{id}

Steps:

Step	Consumer Action	Expected System Response
1	DELETE /classes/{id} without JWT	HTTP 401
2	DELETE /classes/{id} with non-ApiAdmin JWT	HTTP 403

Expected outcome: HTTP 401 or 403 Max execution time: 5s

---

Device Auto-Registration (AZ-196)

FT-P-18: POST /devices Returns Serial / Email / Password

Summary: First call to POST /devices returns the next serial in the azj-NNNN sequence with a generated email and 32-char hex password. Traces to: AZ-196 AC-1 Category: Device Provisioning

Preconditions:

• Caller authenticated as ApiAdmin
• No (or known-prior) CompanionPC users in DB

Input data: POST /devices with no body, ApiAdmin JWT

Steps:

Step	Consumer Action	Expected System Response
1	POST /devices with ApiAdmin JWT	HTTP 200 with serial matching ^azj-\d{4}$, email = {serial}@azaion.com, password = 32 lowercase hex chars

Expected outcome: HTTP 200, all three fields shaped per spec Max execution time: 5s

---

FT-P-19: Sequential Device Serials

Summary: Repeated calls to POST /devices yield strictly increasing serial numbers. Traces to: AZ-196 AC-2 Category: Device Provisioning

Preconditions:

• Most recent CompanionPC user has a known serial azj-NNNN

Input data: POST /devices twice in succession

Steps:

Step	Consumer Action	Expected System Response
1	POST /devices → record serial S1	HTTP 200
2	POST /devices → record serial S2	HTTP 200
3	Parse the numeric suffix of both	numeric(S2) == numeric(S1) + 1

Expected outcome: HTTP 200, suffix increments by exactly 1 Max execution time: 5s

---

FT-P-20: Returned Device Credentials Can Login

Summary: The plaintext password returned by POST /devices succeeds against POST /login (and the persisted hash is therefore correct). Traces to: AZ-196 AC-3, AZ-196 AC-4 Category: Device Provisioning

Preconditions:

• Caller authenticated as ApiAdmin

Input data: Use the response from POST /devices as {Email, Password} to POST /login

Steps:

Step	Consumer Action	Expected System Response
1	POST /devices with ApiAdmin JWT	HTTP 200, {Serial, Email, Password} returned
2	POST /login with the returned Email and Password	HTTP 200 with non-empty JWT

Expected outcome: HTTP 200 on login; persisted user has Role=CompanionPC, IsEnabled=true (verified by AdminApi behaviour rather than direct DB inspection) Max execution time: 5s

---

FT-N-14: POST /devices Without ApiAdmin JWT

Summary: POST /devices requires apiAdminPolicy. Traces to: AZ-196 AC-5 Category: Device Provisioning

Input data: POST /devices

Steps:

Step	Consumer Action	Expected System Response
1	POST /devices without JWT	HTTP 401
2	POST /devices with non-ApiAdmin JWT	HTTP 403

Expected outcome: HTTP 401 or 403 Max execution time: 5s

---

Resources OTA Update Check (AZ-183) — REVERTED post-cycle-1

The OTA update check & publish feature shipped in cycle 1 was reverted later the same day after the security audit (finding F-1: /get-update disclosed plaintext per-resource encryption keys to any authenticated caller). The OTA delivery model itself was deemed obsolete in the target architecture.

The scenarios FT-P-21, FT-P-22, FT-P-23 are retained here as ID placeholders so previously-cited references resolve. Their bodies are intentionally collapsed because the underlying endpoints, service, entity, table, and the e2e test class ResourceUpdateTests.cs were all removed. See _docs/02_document/system-flows.md (Flow F10) and _docs/05_security/security_report.md (finding F-1) for context.

Removed Test ID	Was tracing	Disposition
FT-P-21	AZ-183 AC-2	Removed — endpoint and test deleted
FT-P-22	AZ-183 AC-3	Removed — endpoint and test deleted
FT-P-23	AZ-183 AC-5	Removed — endpoint and test deleted

---

Hardware-Binding Removal (AZ-197)

FT-N-15: Hardware Endpoints Removed

Summary: The legacy PUT /users/hardware/set endpoint and the POST /resources/check endpoint have been removed and now return 404. Traces to: AZ-197 AC-2 Category: Authorization & Routing

Preconditions:

• Updated admin API build (post-AZ-197)

Input data: PUT /users/hardware/set and POST /resources/check

Steps:

Step	Consumer Action	Expected System Response
1	PUT /users/hardware/set with ApiAdmin JWT	HTTP 404
2	POST /resources/check with ApiAdmin JWT	HTTP 404

Expected outcome: HTTP 404 on both routes Max execution time: 5s

Note: AZ-197 AC-1 (resource download works without Hardware) is implicitly covered by the existing FT-P-09 / FT-P-10 scenarios once their request bodies are aligned with the new wire shape. AZ-197 AC-3..AC-8 are internal-signature / build-system invariants and are verified at build/CI time, not via a blackbox HTTP scenario.