Landlord API — Slice 1: Foundation

Summary

Landlords can already be issued Better Auth API keys, but the rental API cannot read them. Slice 1 makes a key a valid identity, decides what each key may do, and freezes a public /api/v1/rental contract — without adding a single new business endpoint.

• Slice 1 of 5 — Foundation
• Runtimes Go API, Bun auth, rental portal
• Surface 10 frozen v1 routes, key-only
• New tables None — existing columns only
• Review history 16 questions, 12 contradictions, all closed
• Remaining gate Verification spike — gates shipping, not starting

The document was approved on 2026-09-19, put through a design review on 2026-09-20, and the last open product decision — rate-limit behaviour — was settled on 2026-09-21. Status is Approved, ready for implementation plan.

The five slices

The full ask spans five independent subsystems. The decomposition and the order were approved before this document was written.

Current state — existing code

Verified against the repository on 2026-09-19, re-verified and extended 2026-09-20. Every row below was read, not assumed.

Auth and keys

Rental routing today

flowchart TD
    G["/api/rental"] --> P["protected: AuthMiddleware + AuditContext"]
    P --> OPEN["contacts, offers, agreements,
tenancies, payments, threads"]
    P --> PROPS["/properties · RequireLandlord"]
    P --> LIST["/listings · RequireLandlord"]
    P --> ADM["/admin · RequireJWTRole"]
    PUB["/api/public/rental"] --> ANON["no middleware at all"]
    

Audit storage — three tables, one usable

Write pattern to copy: digitalworker/adapter/outbound/persistence/postgresql/audit_logger.go:24-41.

verifyApiKey in the installed plugin

That last row is why the verification spike exists.

Decisions

Original decisions (2026-09-19)

Decisions added by the design review

D11 consequence — real cost per request

Architecture

The request flow

flowchart TD
    C["Caller sends x-api-key"] --> M["APIKeyAuthMiddleware
v1 allowlist only"]
    M --> B["Bun verify
landlord configId"]
    B -->|invalid| E401["401 invalid_api_key"]
    B -->|infra failure| E503["503 auth_unavailable"]
    B --> S["Go reads account state + roles"]
    S -->|banned, deleted, inactive| E403["403 account_unavailable"]
    S --> R["Redis hourly allowance"]
    R -->|exhausted| E429["429 rate_limited"]
    R -->|Redis down| ER["503 rate_limit_unavailable"]
    R --> K["RequireKeyScope"]
    K -->|no scope| E403B["403 insufficient_permission"]
    K --> L["v1 landlord gate"]
    L --> H["Handler"]
    

1. Key arrives

   Caller sends x-api-key: grm_live_… to Go at /api/v1/rental/….

2. Verify against Bun

   APIKeyAuthMiddleware — mounted only on the v1 allowlist — asks Bun to verify, naming the landlord configId. Bun calls auth.api.verifyApiKey and returns who the key belongs to and what it may do.

3. Read account state and roles

   Go reads from the database: the row exists, is not banned, is not deleted, plus users.role and the first members row through the existing buildRoles.

4. Set the actor

   User, roles, key id, key name, permissions, mode, actor_type go on the request context.

5. Charge the allowance

   Go charges the request against the key's hourly allowance in Redis. Over the allowance is 429 rate_limited.

6. Scope, role, handler

   RequireKeyScope(resource, action) runs per route. Then the v1 landlord gate. Then the handler.

Handlers never learn a key was used. They read user_id as always. Rental is orgless (ADR-0055), so the key path must not require or invent an organization membership; buildRoles is reused only because it already tolerates that.

Ownership of each concern

Revocation, stated plainly

There is no "log out everywhere" for keys. The account-state read is what makes a ban effective.

Failure modes

Go does not refuse to boot without Redis, because that would take the whole API down for a v1-only dependency. It emits an explicit configuration diagnostic at startup naming v1 as degraded. Real Redis is a release-readiness requirement for v1 in development, CI and deployment.

Session callers on legacy routes are unaffected only when their JWT verifies locally inside Go. That is the common case, not all cases: an opaque session token that falls through to validateViaService still reaches Bun. v1 is unaffected in a different sense — it does not serve session callers at all.

Route mounting

v1 mounts an explicit list of handler methods. It does not call the existing RegisterRoutes for properties, because that function also registers upload and proof routes that are out of scope for v1.

Neither runs key handling: no verify call, no scope check, no counter update. Both answer in the v1 envelope so an integrator gets a parseable response rather than a framework default.

Bun changes

Four endpoints, one config change, one guard.

Landlord key management — session-authenticated, own keys only

POST   /api/landlord/api-keys
GET    /api/landlord/api-keys
DELETE /api/landlord/api-keys/:id      (sets enabled = false; never a physical delete)

The server, not the client, fixes: the landlord configId, the prefix, the metadata.mode, the expanded permission map, and referenceId = the session user. It requires the global landlord role.

Internal verification — server-to-server

POST /api/internal/api-key/verify
  x-service-secret: <shared secret>
  { "key": "grm_live_...", "config_id": "<landlord config>" }

200 { "valid": true,
      "user_id": "usr_9",
      "key_id": "key_abc",
      "key_name": "propertyguru-sync",
      "permissions": { "listings": ["read","write"], "properties": ["read","write"] },
      "metadata": { "mode": "live" },
      "rate_limit": { "limit": 1000, "window_ms": 3600000 } }

401 { "valid": false, "code": "invalid_api_key" | "key_disabled" | "key_expired" }
429 { "valid": false, "code": "rate_limited", "retry_after": 42 }
503 { "valid": false, "code": "auth_unavailable" }

The endpoint names the landlord configId explicitly and checks it. Keys from the default CLI config are therefore invalid on v1 — validateApiKey (index.mjs:1638) checks configId strictly.

Config change

A second apiKey config for landlords, with enableSessionForAPIKeys: false, enableMetadata: true, and its rate limiter disabled, so only Go's limiter can reject a request. Nothing changes for the default CLI config.

Guard on the public plugin routes

/api/auth/api-key/* still exists and the CLI still needs create (ADR-0011).

Go changes

1. BetterAuthValidator.ValidateAPIKey(ctx, key) — the HTTP call above, beside the existing validateViaHTTP.
2. APIKeyAuthMiddleware — new, mounted only on the v1 allowlist. AuthMiddleware is not modified.
3. RequireKeyScope(resource, action) — new middleware. Named this way because RequirePermission is already taken in the same package (better_auth_rbac.go:75) with different semantics.
4. A v1 landlord gate returning the v1 envelope. RequireJWTRole and its pinned denial contract stay exactly as they are.
5. A v1 error renderer, injected per route group.
6. An audit writer on port.Repos.
7. The hourly limiter and its Lua script, plus startup validation of the Redis deployment constraint.

Permissions

Two actions: read, write. A delete is a write. The landlord ticks plain-language bundles; we store the expanded map. Bun owns the expansion table and is the only writer. Go consumes the expanded map as returned by the verify endpoint and never re-derives a bundle.

The full vocabulary is stored from Slice 1 so that keys issued now keep working unchanged as later slices open endpoints. The form shows every bundle; bundles with no reach are rendered disabled with the accurate reason — not silently removed, and not labelled "read only" when no read exists either.

The gate

v1 is key-only (D13). There are no session callers on it.

A cookie or Authorization header on a v1 route is ignored. It cannot raise or lower the caller's authority. Legacy /api/rental/... is unchanged: session callers only, no key handling, no permission gate. The two surfaces do not share an identity path.

Rate limiting — settled 2026-09-21

The decision

A true hourly allowance, configurable per key, default 1000 per hour. The hour is a fixed UTC clock hour. It resets on the boundary whether the caller was busy or idle. There is no inactivity requirement. This is deliberately not a rolling or sliding window, and the document must not be read as promising one.

Why the plugin's limiter could not be used

index.mjs:1573-1631: the counter resets only when now - lastRequest > timeWindow, and every successful call updates lastRequest. A caller in continuous traffic therefore never resets — an idle-window limiter, not an hourly one. remaining and lastRefillAt belong to a separate quota mechanism and do not describe it.

The pre-review draft derived its headers from rate_limit_max, remaining and last_refill_at. That mapping was wrong at the source and is withdrawn. The plugin's limiter is switched off for the landlord config so two limiters can never both reject a request; the CLI config keeps it.

Where each part lives

Key identity, revocation, expiry

Bun / Better Auth (unchanged, D9)

Allowance value, validated at creation

Bun, stored in rate_limit_max

Window length

fixed at 3,600,000 ms; not per-key

Counting and rejection

Go, against shared Redis

Published headers

Go, from the limiter's own result

The counter

One Redis key per verified API key ID — never the raw key, never a hash of it. The value holds the bucket number and the count for that bucket.

1. Read the clock from Redis

   The script reads the current time from Redis TIME. Redis is the single clock, so instances with skewed host clocks cannot split one hour into two buckets.

2. Derive the bucket

   The UTC clock-hour bucket number comes from that time.

3. Reset a stale bucket

   If the stored bucket number is older, the count resets to zero.

4. Check before counting

   If the count has already reached the allowance, the script returns "rejected" and leaves the count unchanged.

5. Otherwise increment

   Increment, and set the expiry to the next boundary.

6. Return the verdict

   Admitted or rejected, the count, the allowance and the reset timestamp.

One declared key per call. No dynamic access to undeclared keys, so the script stays correct under Redis Cluster.

Headers

Always sent on a v1 response produced by the limiter, including the 429. Derived from the atomic result, never from plugin columns.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1789812000      (next UTC hour boundary, unix seconds)
Retry-After: 42                    (429 only; whole seconds to that boundary)

When authentication fails, or Redis is unavailable, no counters exist — so no counter headers are sent. Nothing is invented.

Known behaviour, stated rather than hidden

Redis deployment constraint

The counter is live state. If it is lost, allowances silently reset.

If the deployment cannot be validated, v1 answers 503 rate_limit_unavailable rather than counting on state it cannot trust.

Attribution and audit

D3 selected all four items. Slice 1 delivers the two that make D1 honest. The other two are product surface and stay in Slice 2, stated as such.

Declaration source

New nullable columns on rental_properties, beside the existing declaration fields: declaration_source, declaration_api_key_id, and the key name snapshot.

Nullable, because historical declarations have no source and none may be invented for them. Submit and any review-forcing edit or resubmission stamp these fields inside the same write, so a stamp and its row change cannot diverge.

This is an engineering attribution requirement. It is not a legal claim, and no legal opinion is relied on. ADR-0059 concerns agreement signatures, ADR-0057 listing slugs, ADR-0058 agreement documents — none of them governs the ownership declaration.

Key-write audit

Every successful v1 write records one row in the existing audit_log: actor user, actor_type, key id, key name, action, entity type, entity id, trace id, in details.

organization_id is written as '', which is the column's existing default and the schema's representation of an unscoped record (models.go:209-229). No organization row is created, referenced or implied. Rental audit queries scope by entity_type and owner, never by organization.

audit_trails keeps doing what it does — row snapshots with no actor. The two systems are distinct (ADR-0007) and neither replaces the other.

Key management

No new tables. Every column already exists on apikey.

The page lives in the rental portal at /landlord/api-keys, behind the existing LandlordRoute (frontend/solidstart/apps/rental/src/routes/landlord/LandlordRoute.tsx). Not the admin panel: ADR-0063 moved the landlord workspace out of panel, and a panel deploy must not be able to break a paying rental customer. It calls the Bun endpoints with the shared core auth client, and adds no Go CRUD.

Create form

The allowance stays landlord-configurable, as the original create form intended. The installed plugin refuses client-set rateLimit fields (index.mjs:725), so the value travels as a request field to the Bun management endpoint, which validates it against bounds and writes it.

The maximum is a deployment setting, not a published tier. Nothing in the public contract promises it, and changing it is a configuration change rather than a contract change. The window is not configurable — it is one UTC clock hour, always.

Mode is immutable after issue. The prefix and metadata.mode must agree; the server validates that pair. A key whose mode is absent or malformed fails closed — it does not default to live. A key with empty or missing permissions is denied on every v1 route. No component writes the apikey table directly.

Reveal rule and list view

The full key is shown once, at creation. Never again. The list view shows start only, for example grm_live_8f3a…; get and list responses redact the key and its hash.

The list shows name, permissions, hourly allowance, last_request rendered as "last used", expiry, mode, and a revoke button. Revoke sets enabled = false. last_request stays the source for "last used" even though the plugin's limiter is off for this config — the plugin still stamps it. A regression test pins that, so an upgrade that changes it fails loudly instead of silently emptying the column. Nothing derives "last used" from Redis or from the audit log.

Test mode

Test keys carry the prefix grm_test_. A key's prefix cannot change after issue, so the prefix is reserved now rather than in Slice 4. Row marking (is_test on listings and properties) is Slice 2 work, so in Slice 1 a test key reads normally and is blocked on every write with 403 test_mode_unavailable.

The form labels the mode control accordingly: a test key is read-only until Slice 2. The control stays, because a sandbox was part of the approved D7 scope and removing it would be a product change. Slice 2 lifts the block and marks the rows — avoiding the trap where a test key silently writes real listings into the admin review queue.

The frozen public contract

Go currently has three error shapes: the global handler's {success, message, code} where code is HTTP status text; RequireJWTRole's {error, code} which deliberately bypasses that handler; and validation responses that add a fields list of strings. Repo-wide normalisation was attempted before and reverted. This design does not repeat that.

/api/rental/...      portal, sessions   unchanged forever
/api/v1/rental/...   public, keys       frozen contract

Same handlers underneath, different renderer. There is no forked route tree.

Error envelope

{
  "error": {
    "code": "validation_failed",
    "message": "validation failed",
    "fields": [ "monthly_rent" ]
  },
  "request_id": "trace_9f2a..."
}

fields appears only on validation failures, and it is a list of field names — the existing []string shape (property_handler.go:329). That is settled, not deferred. Per-field reasons are not published, because the validation layer does not produce typed reason data today. A non-validation error carries no fields key at all.

The renderer is injected and selected per route group, and runs before the handler commits output. It maps domain sentinels to codes; it never matches English message strings and never rewrites response bytes. It covers bind and validation failures, early auth failures, 404 and 405, and a sanitised 500 internal_error that leaks nothing. The trace id is created before authentication, so a request that fails at the key check still carries a request_id a landlord can quote. Legacy responses are preserved by regression goldens.

code is a stable snake_case string, never HTTP status text. Once published it cannot change.

Success bodies

Rental entities are already consistently snake_case (property_id, monthly_rent, deposit_months) and are reused rather than duplicated into parallel public DTOs. The risk is that an internal field rename silently breaks an outsider's script. The repo's existing nric_masking_golden_test.go and contact_reveal_golden_test.go pin response JSON only; the v1 harness is table-driven and pins method, route, request body, query, status, response body and error codes, and the same table is asserted against the OpenAPI document.

Endpoints in v1 for Slice 1

GET    /api/v1/rental/properties
POST   /api/v1/rental/properties
GET    /api/v1/rental/properties/:id
PUT    /api/v1/rental/properties/:id
GET    /api/v1/rental/properties/:id/photos
GET    /api/v1/rental/listings/:id
POST   /api/v1/rental/listings
PUT    /api/v1/rental/listings/:id
POST   /api/v1/rental/listings/:id/submit
POST   /api/v1/rental/listings/:id/withdraw

All ten exist today (property_handler.go:37-50, listing_handler.go:34-39) and are mounted by explicit selection.

The OpenAPI document is hand-written at backend/go/openapi/rental-v1.yaml. The Bun generator is a stub and Go has none, so generating one is its own project. Slice 1's surface is small enough to write by hand, and the contract table is asserted against it, so the document cannot drift silently.

Internal endpoint isolation

fly.toml exposes one public http_service on port 3100. There is no evidence of any path-deny capability at that edge, so a path rule is not relied on.

One secret is sufficient for Slice 1. Rotation is a coordinated restart and is documented as such; two-secret machinery is not built on speculation. Private connectivity between the two runtimes is a release acceptance check, not an assumption — it is not claimed to be provisioned already.

Testing

Integration tests follow the existing recipe: pg-test on :55432, migrations run from a directory with no .env, because backend/go/.env points at UAT. The limiter tests additionally need a real Redis — cache/redis_client.go:20-47 tolerates an absent one, so a suite without Redis would pass vacuously.

Verification spike — acceptance prerequisite

The installed plugin has a catch converting non-API database exceptions into INVALID_API_KEY with no reason (index.mjs:1808-1825). Mapping that to 401 would make an integrator rotate a good key — the exact outcome the failure-mode rule exists to prevent.

Task 3a is a spike: build request-scoped instrumentation at the adapter level that observes the key lookup and the counter update for that request, so a genuine invalid key can be told apart from an infrastructure failure.

Tasks

Regenerated after the review. The earlier 14-task list assumed one Bun endpoint, a panel UI, a shaping middleware, and no audit writer.

Tasks 2–11 are the spine. Tasks 12, 19, 20 and 27 are the contract. Tasks 23–29 are the limiter. Task 21 is the only frontend work. Task 3a gates shipping, not starting: implementation proceeds, and the spike's outcome decides whether it can ship.

Out of scope for Slice 1

external_ref, address fingerprint, Idempotency-Key, cross-landlord duplicate flagging, photo sync of any kind, proof upload over the API, outbound webhooks, the CLI, test-row marking, listing origin, and the admin API badge. Each belongs to a later slice. Slice 1 exposes what already exists, safely.

Note the deliberate asymmetry: the media and proofs permissions ship in Slice 1 while their upload endpoints do not. Permissions are stored early so a key issued today needs no reissue when Slice 3 lands.

Open risks

Follow-ups

• Recommended ADR: the config and route trust boundary — one landlord configId with sessions disabled and its plugin limiter off, v1 key-only with the hourly allowance in Go, legacy session-only. One ADR covering the whole settled boundary, now that the rate decision is made.
• Revisit the verify-cache question in Slice 3, together with bulk photo import. Any proposal must answer the revocation-delay objection.
• Revisit the provisional 10000 ceiling once real usage exists. It is a deployment setting, so changing it is not a contract change.

The ownership-marker rationale stays with its source references. Not every implementation decision earns an ADR.