feat: basic backend #158

julian · 2026-04-05T10:16:37-04:00

julian commented

2026-04-05 10:16:37 -04:00

Description

Backend implementation as per the spec #11 (backend.md)

Testing Checklist

This testing can be fully automated using an LLM and cURL , this list is merely a checklist of the possibilities covered by the changes in this branch.

Setup

Server running with JWT_SECRET set (no SMTP → OTP codes appear in the server log).
One sys-admin seeded out-of-band: karriba-seed -email [email protected].
Base URL: http://localhost:8080. All responses are JSON; errors use {"error":{"code","message"}}.

1. Health & Auth

GET /v1/health → 200 {"status":"ok","version":...} (no auth)
POST /v1/auth/otp/request (registered contact) → 200, expires_in:900; code appears in log
POST /v1/auth/otp/request (unregistered contact) → identical 200 (no code generated)
POST /v1/auth/otp/verify with the logged code → 200 with access_token, refresh_token, correct user payload
POST /v1/auth/otp/verify wrong code → 400 INVALID_OTP
POST /v1/auth/refresh with the returned token → 200 with a new refresh_token; reusing the old one → 401 REVOKED_TOKEN

2. Access Control

Any protected endpoint with no / invalid token → 401
Sys-admin token on a manager-only endpoint (list users) → 403 INSUFFICIENT_ROLE
Member accessing another org → 403

3. Orgs (sys-admin token)

POST /v1/orgs → 201; initial_manager.role:"manager"; a tenant DB file for the new org id is created
GET /v1/orgs/:id → 200 with user_count
PATCH /v1/orgs/:id rename → 200; archive, then confirm members get 403 while sys-admin still reads it

4. Users (manager token)

GET /v1/orgs/:id/users → 200
POST /v1/orgs/:id/users invite member → 201
Invite with a bad role (e.g. "supervisor") → 400 INVALID_ROLE
Demote the only manager → 400 ORG_REQUIRES_MANAGER
Member self-leave DELETE .../users/:selfId → 204

5. Pagination

GET /v1/orgs/:id/users?limit=1 → 1 item + non-null next_cursor
Re-request with ?limit=1&cursor=<value> → next page; last page has next_cursor:null

6. Entitlements

GET /v1/orgs/:id/entitlements (any member) → 200
PUT /v1/orgs/:id/entitlements (sys-admin) ["pesticide","cloud_sync"] → 200
PUT ["cloud_sync"] alone → 400 ENHANCEMENT_REQUIRES_STANDALONE (with module/requires)
PUT unknown module → 400 INVALID_MODULE
PUT as manager/member → 403

7. Rate Limiting (needs a proxy-free direct hit)

Fire >30 auth requests from one IP within a minute → excess → 429 RATE_LIMITED
Confirm normal traffic recovers after the window

Notes

Timestamps are RFC 3339 UTC; IDs are UUIDv7.
Automated coverage exists for: OTP lockout/expiry, refresh reuse family-revocation, all role guards, invalid module/role codes, and the entitlement→tenant-DB sync.

# Description Backend implementation as per the spec #11 (backend.md) # Testing Checklist This testing can be fully automated using an LLM and cURL , this list is merely a checklist of the possibilities covered by the changes in this branch. ## Setup - Server running with `JWT_SECRET` set (no SMTP → OTP codes appear in the server log). - One sys-admin seeded out-of-band: `karriba-seed -email [email protected]`. - Base URL: `http://localhost:8080`. All responses are JSON; errors use `{"error":{"code","message"}}`. ## 1. Health & Auth - [x] `GET /v1/health` → `200 {"status":"ok","version":...}` (no auth) - [x] `POST /v1/auth/otp/request` (registered contact) → `200`, `expires_in:900`; code appears in log - [x] `POST /v1/auth/otp/request` (unregistered contact) → identical `200` (no code generated) - [x] `POST /v1/auth/otp/verify` with the logged code → `200` with `access_token`, `refresh_token`, correct `user` payload - [x] `POST /v1/auth/otp/verify` wrong code → `400 INVALID_OTP` - [x] `POST /v1/auth/refresh` with the returned token → `200` with a **new** `refresh_token`; reusing the old one → `401 REVOKED_TOKEN` ## 2. Access Control - [x] Any protected endpoint with no / invalid token → `401` - [x] Sys-admin token on a manager-only endpoint (list users) → `403 INSUFFICIENT_ROLE` - [x] Member accessing another org → `403` ## 3. Orgs (sys-admin token) - [x] `POST /v1/orgs` → `201`; `initial_manager.role:"manager"`; a tenant DB file for the new org id is created - [x] `GET /v1/orgs/:id` → `200` with `user_count` - [x] `PATCH /v1/orgs/:id` rename → `200`; archive, then confirm members get `403` while sys-admin still reads it ## 4. Users (manager token) - [x] `GET /v1/orgs/:id/users` → `200` - [x] `POST /v1/orgs/:id/users` invite member → `201` - [x] Invite with a bad role (e.g. `"supervisor"`) → `400 INVALID_ROLE` - [x] Demote the only manager → `400 ORG_REQUIRES_MANAGER` - [x] Member self-leave `DELETE .../users/:selfId` → `204` ## 5. Pagination - [x] `GET /v1/orgs/:id/users?limit=1` → 1 item + non-null `next_cursor` - [x] Re-request with `?limit=1&cursor=<value>` → next page; last page has `next_cursor:null` ## 6. Entitlements - [x] `GET /v1/orgs/:id/entitlements` (any member) → `200` - [x] `PUT /v1/orgs/:id/entitlements` (sys-admin) `["pesticide","cloud_sync"]` → `200` - [x] `PUT` `["cloud_sync"]` alone → `400 ENHANCEMENT_REQUIRES_STANDALONE` (with `module`/`requires`) - [x] `PUT` unknown module → `400 INVALID_MODULE` - [x] `PUT` as manager/member → `403` ## 7. Rate Limiting (needs a proxy-free direct hit) - [x] Fire >30 auth requests from one IP within a minute → excess → `429 RATE_LIMITED` - [x] Confirm normal traffic recovers after the window ## Notes - Timestamps are RFC 3339 UTC; IDs are UUIDv7. - Automated coverage exists for: OTP lockout/expiry, refresh reuse family-revocation, all role guards, invalid module/role codes, and the entitlement→tenant-DB sync.

julian self-assigned this

2026-04-05 10:16:37 -04:00

julian added 4 commits

2026-04-05 10:16:37 -04:00

feat(backend): first backend draft 8617a980a8

test(api): add coverage for api tests 125a500451

Merge branch 'infrastructure-backend-design' into 11-backend d2f92cdf6b

refactor(backend): address spec changes 2615017a54

addison commented

2026-04-11 06:24:22 -04:00

Be sure also to hook up the CI/CD to run go tests

julian added 4 commits

2026-04-26 20:08:52 -04:00

Merge branch 'infrastructure-backend-design' into 11-backend 32cb5b3397

refactor(backend): comply with new backend.md spec 6a68da6b35

fix(backend): spec concerns fc6c003d2e

Merge branch 'infrastructure-backend-design' into 11-backend

Backend CI / test (pull_request) Successful in 1m8s

Details

6c25e99097

julian added 1 commit

2026-04-26 20:17:33 -04:00

test(backend): add further coverage

Backend CI / test (pull_request) Successful in 22s

Details

bde5e86e44

julian changed title from ~~WIP: feature: backend~~ to feature: backend

2026-04-26 20:18:52 -04:00

julian added 4 commits

2026-07-12 22:21:00 -04:00

Merge remote-tracking branch 'origin' into 11-backend 262d2ed993

refactor(backend): revise compliance with backend spec 7e66660b13

test(backend): add coverage for INVALID_ROLE, rate limitation and tenant DB test gaps 244cea6dc8

test(backend): separate api_test into multiple smaller files

Backend CI / test (pull_request) Successful in 2m27s

Details

Flutter CI / test (pull_request) Successful in 3m1s

Details

PR Build / build (pull_request) Successful in 7m41s

Details

bc36d27072

julian changed target branch from infrastructure-backend-design to main

2026-07-12 22:22:24 -04:00

julian added 1 commit

2026-07-12 22:30:39 -04:00

Merge remote-tracking branch 'origin' into 11-backend

Backend CI / test (pull_request) Successful in 1m47s

Details

06f3b2379e

forgejo-actions commented

2026-07-12 22:31:04 -04:00

📦 Build Successful!

Commit: bc36d27
Size: 59M

Download APK

## 📦 Build Successful! **Commit:** `bc36d27` **Size:** 59M [Download APK](https://git.kwila.cloud/kwila/karriba/actions/runs/1398/artifacts/karriba-apk)

julian added 1 commit

2026-07-12 22:49:24 -04:00

refactor(backend): cahnge sql drive to mattn CGO library

Backend CI / test (pull_request) Failing after 1m15s

Details

ae5cdbff4d

julian added 1 commit

2026-07-12 22:56:46 -04:00

refactor(ci): possible fix for test ci

Backend CI / test (pull_request) Successful in 1m30s

Details

0b00d86c56

julian requested review from addison

2026-07-12 22:58:12 -04:00

julian commented

2026-07-12 22:59:54 -04:00

This should be ready for review 🫡This should be one of the last BIG changes 😅

🎉 1

addison commented

2026-07-13 08:55:04 -04:00

Great! I plan to review this week, Thursday at the latest.

addison commented

2026-07-13 08:56:37 -04:00

All the stuff mentioned in the MR description also has automated tests to run in CI?

julian commented

2026-07-13 11:16:35 -04:00

@addison wrote in #158 (comment):

All the stuff mentioned in the MR description also has automated tests to run in CI?

I think most of it should be covered. There may be some gap I'm unaware of.

@addison wrote in https://git.kwila.cloud/kwila/karriba/pulls/158#issuecomment-3046: > All the stuff mentioned in the MR description also has automated tests to run in CI? I think most of it should be covered. There may be some gap I'm unaware of.

addison reviewed

2026-07-13 17:44:06 -04:00

backend/Dockerfile Outdated

					
				@ -0,0 +4,4 @@

				COPY go.mod go.sum ./

				RUN go mod download

				COPY . .

				RUN CGO_ENABLED=0 go build -o karriba-server ./cmd/karriba-server

We need to enable cgo, right? Otherwise everything is going to fail inside this image.

addison marked this conversation as resolved

addison added 2 commits

2026-07-13 17:53:50 -04:00

docs(auth): document proxy trust assumption 2d09a7b6cd

test: prove refresh bug

Backend CI / test (pull_request) Failing after 1m14s

Details

b5c1f922e3

addison commented

2026-07-13 17:54:43 -04:00

b5c1f922e3 adds test case to show bug in refresh handling

b5c1f922e3 adds test case to show bug in refresh handling

addison added 1 commit

2026-07-13 17:57:46 -04:00

test(auth): prove concurrent OTP consumption

Backend CI / test (pull_request) Failing after 1m15s

Details

3b7fb60fba

addison commented

2026-07-13 17:57:57 -04:00

3b7fb60 has a test for concurrent OTP bug

3b7fb60 has a test for concurrent OTP bug

addison added 1 commit

2026-07-13 17:59:07 -04:00

test(org): align archived access with spec

Backend CI / test (pull_request) Failing after 1m15s

Details

1d8a1c0f88

addison commented

2026-07-13 18:00:30 -04:00

1d8a1c0 has a fix for the test - members of archived organizations need read access to the orgs endpoint so they know that their organization is archived - see line 671 of spec 11

1d8a1c0 has a fix for the test - members of archived organizations need read access to the orgs endpoint so they know that their organization is archived - see line 671 of spec 11

addison added 1 commit

2026-07-13 18:03:12 -04:00

test(entitlements): reject tenant sync false success

Backend CI / test (pull_request) Failing after 1m13s

Details

5f28d53704

addison commented

2026-07-13 18:03:50 -04:00

5f28d53 has a test for bug with entitlements handling

5f28d53 has a test for bug with entitlements handling

addison requested changes

2026-07-13 18:04:42 -04:00

Dismissed

addison left a comment

I used codex to help me find a few concerns, and added test cases to show the different situations.

It would also be good to include a CI job to build the docker image to make sure it is fine in every PR.

I used codex to help me find a few concerns, and added test cases to show the different situations. It would also be good to include a CI job to build the docker image to make sure it is fine in every PR.

julian added 2 commits

2026-07-13 20:30:47 -04:00

refactor(backend): address test errors 0c1a169953

chore(ci): add build job

Backend CI / build (pull_request) Successful in 1m21s

Details

Backend CI / test (pull_request) Successful in 1m55s

Details

f102274670

julian commented

2026-07-13 20:35:28 -04:00

Addressed the test concerns and added the build CI job 😄

addison changed title from ~~feature: backend~~ to feat: basic backend

2026-07-14 13:53:12 -04:00

addison commented

2026-07-14 14:11:33 -04:00

This one might take a few review iterations since it is so big 😅

addison reviewed

2026-07-14 14:14:11 -04:00

backend/migrations/tenant/001_initial.sql

					
				@ -0,0 +1,9 @@

				-- Tenant DB schema mirrors the Flutter app's Drift schema.

				-- This is a placeholder; the full schema should be kept in sync

When do we replace the placeholder? In a separate PR or in the cloud sync spec?

We could make it in a separate PR to avoid making adding much more to this one since it is already this big😅

👍 1

Yeah, I agree. Especially if we pivot to a separate sync project with an event-log approach.

addison marked this conversation as resolved

addison added 2 commits

2026-07-14 14:30:42 -04:00

test(api): prove archived org mutations remain possible f472905250

test(store): prove tenant connection eviction race

Backend CI / test (pull_request) Failing after 1m49s

Details

Backend CI / build (pull_request) Successful in 1m23s

Details

6abf284af5

addison added 1 commit

2026-07-14 14:41:25 -04:00

test: prove concurrent refresh bug

Backend CI / build (pull_request) Successful in 1m13s

Details

Backend CI / test (pull_request) Failing after 1m39s

Details

86045678a3

addison commented

2026-07-14 14:44:50 -04:00

A few more tests for a few more broken edge cases. Auth systems are tricky 😅

addison added 1 commit

2026-07-14 14:44:54 -04:00

test(store): prove concurrent OTP creation race

Backend CI / build (pull_request) Successful in 1m13s

Details

Backend CI / test (pull_request) Failing after 1m39s

Details

4f81fe6dd4

addison changed title from ~~feat: basic backend~~ to WIP: feat: basic backend

2026-07-15 08:52:47 -04:00

julian added 14 commits

2026-07-23 22:25:26 -04:00

Merge branch 'main' into 11-backend cf099599ed

fix(store): serialize CreateOTP 0fca4f9b05

fix(auth): close concurrent refresh race faf7146b83

fix(store): close tenant connection eviction race 0a7ee759a6

fix(api): block archived org mutations 7501c1465e

test(backend): reorganize admin_test into smaller more readable files 2a244bbae7

refactor(api): consolidate JSON response helpers f67bcf7cb7

test(api): consolidate test request helpers d6fd42c544

feat(auth): harden JWT validation and rate limiting a158173a6f

feat(api): bound OTP dispatch and improve expiry checks 8334e4c375

refactor(store): membership, module and pool helpers d6f8aa50b8

refactor(api): extract shared org user provisioning f10d2305cb

feat(api): entitlement update validation 8c0e163bdb

feat(middleware): propagate archived state through bypassed auth

Backend CI / build (pull_request) Successful in 1m5s

Details

Backend CI / test (pull_request) Successful in 2m33s

Details

Flutter CI / test (pull_request) Successful in 3m16s

Details

PR Build / build (pull_request) Successful in 8m19s

Details

993108274f

julian added 1 commit

2026-07-23 22:27:26 -04:00

Merge branch 'main' into 11-backend

Backend CI / test (pull_request) Successful in 2m6s

Details

Backend CI / build (pull_request) Successful in 5s

Details

49e48291ee

forgejo-actions commented

2026-07-23 22:36:16 -04:00

📦 Build Successful!

Commit: 9931082
Size: 62M

Download APK

## 📦 Build Successful! **Commit:** `9931082` **Size:** 62M [Download APK](https://git.kwila.cloud/kwila/karriba/actions/runs/1611/artifacts/karriba-apk)

julian changed title from ~~WIP: feat: basic backend~~ to feat: basic backend

2026-07-23 23:47:02 -04:00

addison added 1 commit

2026-07-25 12:04:40 -04:00

fix(backend): address review follow-ups

Backend CI / build (pull_request) Successful in 1m6s

Details

Backend CI / test (pull_request) Successful in 2m24s

Details

3cc2cf8468

addison added 2 commits

2026-07-25 12:46:40 -04:00