Skip to content
catalystcommunityPublic

About

SMB and Household task/calendar/etc stack

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Longhouse

Coordination system for small-to-medium organizations and neighborhoods. Tasks, calendar, projects, members, groups, and skills under a per-house membership model.

See LinkKeys act-as access to let applications act for a user.

Quick start

./tools dev        # postgres (docker, host port 5433) + api + vite, sourcing .env.dev

This starts Postgres in Docker, the Go API, and the Vite dev server, then foregrounds a tail of logs/api.log + logs/vite.log (Ctrl-C just stops the tail, not the services). The SPA is served at http://localhost:5173 and proxies /api/* to the API at localhost:6080.

.env.dev in the repo root holds local-only config (Postgres port, JWT secret, dev-auth flag, initial admin identity) and is gitignored. With LONGHOUSE_ENV=dev and dev-auth enabled, visit /dev-login in the SPA to sign in without a live linkkeys identity provider.

Tear down with:

./tools dev-down   # stops services, keeps the postgres volume

Tests

./tools test       # run all tests (API + webapp)
./tools test-api   # run API tests only
./tools test-web   # run webapp tests only

Layout

  • api/ — Go API server (single CSIL-RPC endpoint, no REST)
  • webapp/ — Zest + TypeScript + Vite SPA
  • clients/ — generated CSIL client libraries, one package per language
  • csil/ — CSIL service/type definitions (source of truth for server + clients)
  • coredb/ — SQL migrations (goose)
  • helm_chart/ — Kubernetes Helm chart
  • deploy/ — per-environment Helm values

Web components

The web app uses Zest and native DOM elements. It has no JSX compiler or application framework. The component library has two parts:

  • webapp/src/ui/ supplies view lifetimes, DOM bindings, state, routing, and the Zest date field.
  • webapp/src/components/ supplies Longhouse controls. These include the task feed, editors, calendar controls, comments, and dependency controls.

LonghouseView extends Zest BaseComponent. Each page owns its subscriptions and cleanup functions. State uses Zest BasicDataService. Navigation uses Zest SimpleRouter. The date field extends Zest DateTimePicker. webapp/src/styles/zest.css maps Zest color roles to the Longhouse palette. Keep the explicit Vite CSS targets: they preserve light-dark() in the build.

To add a view, use el for DOM elements and live for values that change. Use property getters for attributes that read state. Use When for conditional content and Repeat for lists. Repeat keeps rows with the same object identity. Keep row objects stable when a page of results arrives, or an open editor can lose its draft. Use query for requests. It ignores responses after a source change or page removal. Register timers and external listeners with cleanup. Use defineView when a component needs its own Zest element and lifetime.

Use the generated client in data/clients.ts for API calls. Never send an empty recurrenceFreq: the wire enum rejects it. On updates, use clearRecurrence to remove a task or event schedule. Remote calendar edits also send the RRULE. Deploy the API and web images together when introducing this field.

Run npm test and npm run build in webapp/. The tests include view cleanup, request ordering, routing, task paging, and calendar acceptance and recovery. Check native form behavior, focus, scrolling, and narrow layouts in a browser. For a separate local API, set LONGHOUSE_DEV_API_TARGET before npm run dev.

Auth

Sign-in is delegated to linkkeys as the identity provider. Longhouse keeps a local member record that caches the identity data linkkeys releases; who may sign in is controlled by trusted domains and explicit user lists.

The Sign in button uses the instance's home IDP. Select Sign in with another domain to enter name@domain.com. The browser saves this login on the device and keeps it after sign-out. The saved login is only a form value. It does not give access to Longhouse.

AuthService.BeginBrowserLogin checks the domain before it calls DNS or LinkKeys. The home domain is permitted. Any other domain must be trusted by at least one house. Longhouse reads the https= address from the domain's _linkkeys_apis TXT record. It shows an error if the record is absent or invalid, or if the lookup fails. It sends the local username to the IDP as the username form value.

A signed, httpOnly longhouse_login cookie binds the domain and nonce to the browser for ten minutes. The callback checks this cookie, current domain trust, the assertion domain, nonce, and RP audience. Sign-in does not select a house. The verified identity gets its active memberships across houses. An unfinished sign-in from an older server version must start again after this update.

The UI version comes from the release image's Git tag during CI builds. CI passes it through the LONGHOUSE_APP_VERSION Docker build argument. Local builds use version/VERSION.txt when that argument is absent. The tag can precede the automatic update to that file. No UI file needs a manual version change. Page responses require cache validation; hashed assets can stay in the browser cache.

Longhouse sends its own claim request in Rp/sign-request (linkkeys.LonghouseClaimRequest in api/internal/linkkeys/tcp.go). The handle claim is required. A user who declines it cannot sign in. The email, display_name, and avatar_url claims are optional. The RP server does not need an RP_CLAIMS_CONFIG for Longhouse.

The request also names the application (application_id). LinkKeys 0.16.7 and later keep standing consent for each application, and the consent screen shows the display name of the RP API-key account. The application ID comes from LONGHOUSE_LINKKEYS_APPLICATION_ID. When that is empty, it comes from the act-as key file (LONGHOUSE_ACT_AS_KEYS_FILE). Otherwise it is longhouse. Keep it equal to the act-as application ID.

The bearer token snapshots the caller's per-house membership and roles at mint time, so authorization needs no database lookup per request. Staleness is bounded by the token's exp and by the AuthService.Refresh op.

Access bearers expire after 12 hours by default. Set LONGHOUSE_BEARER_TTL_SECONDS to change this lifetime. CLI refresh sessions expire after 30 days by default. Set LONGHOUSE_REFRESH_TOKEN_TTL_SECONDS to change their absolute lifetime. Refresh-token rotation does not extend that lifetime.

Command-line interface

The release binary contains the API server and the Longhouse command-line interface (CLI). Sign in before you use resource commands:

longhouse auth login --url=https://longhouse.example
longhouse auth status

auth login opens a browser. The browser uses the normal linkkeys flow and asks the user to approve the named CLI. For an SSH session, use --no-browser and open the printed URL on another device. The old top-level login, status, refresh, and logout commands remain as aliases.

The CLI stores named profiles in the operating system user configuration directory. The profile file has mode 0600. Each signed-in profile contains a short-lived access bearer and a rotating refresh token. The CLI does not print these values.

longhouse profile add dev --url=https://longhouse.example
longhouse auth login --profile dev
longhouse profile use dev
longhouse profile house use HOUSE_ID

Use noun and verb commands for Longhouse resources:

longhouse task list
longhouse task create "Repair the west gate" --due tomorrow
longhouse task done TASK_ID
longhouse project member add PROJECT_ID MEMBER_ID
longhouse comment add task:TASK_ID --body "Blocked by the permit"
longhouse dependency add task:TASK_ID project:PROJECT_ID

A create or edit command shows a terminal form when required input is missing. Use --interactive to request the form. Use --no-input to stop all prompts.

Plain text is the default output. Use JSON only when a program needs it:

longhouse task create --input task.json --output json
longhouse help task create --json
longhouse api describe TaskService.Create --json

The CLI converts local JSON to generated Go client types. It validates the request and sends CBOR through the CSIL-RPC endpoint. It does not send JSON to the server. Run longhouse help to see the command hierarchy. Run longhouse api list to see every generated CSIL operation. Automated callers can start with longhouse agent instructions --json and longhouse help --json.

The account page lists CLI sessions. A user can revoke a session there. A revoked session cannot refresh again. Its current bearer can work until the configured bearer lifetime ends.

Documentation

  • AGENTS.md — architecture, conventions, and the deploy/dogfood loop
  • docs/rbac.md — access levels, visibility, and the grant model
  • docs/dependencies.md — task and project dependency edges
  • docs/cli_approach.md — CLI hierarchy, input modes, validation, and output

About

SMB and Household task/calendar/etc stack

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages