Skip to content

FEATURES.md

Latest commit

 

History

History
68 lines (46 loc) · 7.17 KB

FEATURES.md

File metadata and controls

68 lines (46 loc) · 7.17 KB
Raw

Features

Self-hosted social publishing platform: one Compose installation per customer; users manage provider accounts, prepare content, publish now or scheduled; providers are plugins; credentials stay encrypted under the customer's control. Tags: P0 must (release blocker) · P1 should · P2/P3 later. [INFRA] = Infra v0.1 · [IG] = Instagram plugin v0.2 · [LATER]. (S n) = ROADMAP step.

Roles: Admin (users, roles, plugin trust/grants/enable, approvals, health; no implicit access to others' content/credentials/DB) · User (own accounts, content, jobs; nothing of others) · Plugin (own process, admin-set trust level, acts for a user only inside an Executioner-initiated call) · Operator (host, Compose, secrets, backups, plugin install via CLI; outside app authorization). Success = Infra v0.1 demo script (ROADMAP Step 15), then Instagram on a real eligible test account. Non-goals (v0.1/v0.2): hosted SaaS · UI plugin upload/marketplace · plugin browser code · plugin network sandbox · AI/TikTok/other providers · image/video generation · Kubernetes/HA · analytics, approvals of posts, billing · promises about third-party API availability · a Docker-controlling runtime manager · any external/remote service for trust decisions.

A. Deployment and operations

  • P0 [INFRA] Compose stack web/server/db (+ proxy profile); networks public, backend, dbnet, egress; only web published (default 127.0.0.1); volumes for DB/media/plugins. (S1)
  • P0 [INFRA] Health/readiness, structured logs, graceful shutdown in dependency order, pinned images, secrets as files via script, hardened containers (read-only, no caps, limits). (S1–2, S15)
  • P1 [INFRA] Backup/restore with a tested drill (DB + media + plugins, key separate); upgrade/rollback procedure; optional TLS proxy profile. (S15)
  • P2 [LATER] S3-compatible media storage.

B. Users, roles, authorization

  • P0 [INFRA] CLI admin bootstrap; login/logout; server-side sessions; admin manages users/roles; every request authenticated and authorized at the Gateway; ownership enforced in the data layer; deny-by-default route ACL; audit of admin, lease, approval and publish actions. (S3, S5–6)
  • P1 [INFRA] Admin password reset; login rate limiting. (S6)
  • P2 [LATER] Explicit sharing between users (only with a defined use case).

C. Server process model

  • P0 [INFRA] Controller (PID 1): ordered start (Gateway → File-System → PMP → Executioner → Watchdog), per-process rights (UID/caps/no_new_privs/rlimits/clean env/private tmp), secret re-homing, crash restart with backoff, crash-loop stop, zombie reaping, signals, reverse-order shutdown (Watchdog first), private channel to the Watchdog. (S2)
  • P0 [INFRA] IPC Gateway as hub: every message between processes passes it; mTLS from web = only way in; per-process identity by socket dir; route table deny-by-default; limits, deadlines, correlation IDs; IPC request format designed in Step 3a. (S3)
  • P0 [INFRA] Watchdog: health checks of all processes through the Gateway, direct probe of the Gateway, states incl. UNKNOWN, restart requests to the Controller, status for the admin page. (S4)
  • P1 [LATER] Landlock/seccomp for plugin processes.

D. Plugin system

  • P0 [INFRA] Plugin-Management process (PMP): strict manifest (main.json), package validation, only writer of the plugins volume, SHA-256 pinning, registry (versions, trust level, requested/granted capabilities, lifecycle), operator CLI install, uninstall with retain/delete. (S9)
  • P0 [INFRA] Executioner: loads enabled plugins as sub-processes (hash check → own UID → rights verified in /proc after spawn), private plugin channel, lifecycle (restart, crash loop), per-request rights check, call contexts, manifest tasks. (S10, S12)
  • P0 [INFRA] Trust and local approval: trusted/untrusted per plugin; untrusted requests held until the admin allows once / always / denies in the web UI or via CLI; timeout = deny; fully local, no external service; all decisions audited. (S11)
  • P0 [INFRA] Host API: JSONB storage, accounts, credential store/lease, media stream/public URL, checkpoint, audit; declarative UI descriptors; Executioner-invoked callbacks and manifest tasks. (S12)
  • P1 [INFRA] SDK + demo plugin with failure injection + manifest validator (in postflowx-server). (S12d)
  • P2 [LATER] UI upload with signatures, staged updates/revocation, catalog; container-per-plugin + egress filtering + provider calls made by the platform (for truly untrusted plugins); P3 iframe plugin UIs; multi-version rollback.

E. Data and secrets

  • P0 [INFRA] Gateway-owned core schema; checksummed ordered migrations; least-privilege DB roles; typed named DB operations only (no raw SQL); credentials encrypted (AEAD, key outside DB, key_id, master key only in the Gateway); credential states ACTIVE/EXPIRING/EXPIRED/REVOKED/REAUTH_REQUIRED. (S5, S12b)
  • P0 [INFRA] File-System process: images/JSON/files on the media volume only via the Gateway; ID-based paths, atomic writes, magic-byte + size validation, owner scoping, quotas, chunked streaming, signed public URLs. (S8)
  • P2 [LATER] Key-rotation tooling, per-user data export/deletion.

F. Publishing and jobs

  • P0 [INFRA] Posts (draft, media refs, target account, provider options); durable job state machine with attempts, leases, bounded retries, terminal states, scheduler in the Executioner; immediate + scheduled (UTC + IANA zone, DST/missed-window policy); idempotency keys; distinct handling of expired token / rate limit / transient / permanent; restart recovery (Executioner and Gateway); OUTCOME_UNKNOWN + Reconcile + user decision when undecidable. (S13)
  • P1 [INFRA] Job history, user-facing error explanations, admin diagnostics. (S13–14)
  • P2 [LATER] Retry tuning, bulk operations, recurring schedules.

G. Web application

  • P0 [INFRA] Frontend + own BFF (typed calls to the Gateway only, no DB); cookie/session + CSRF/Origin; shell, auth views, degraded screen; admin UI (users, plugins, health, approvals); user UI (accounts, composer with schema-driven options, media, jobs); generic OAuth-callback and public-media routes. (S7, S9, S11, S14)
  • P1 [INFRA] Accessible validation/loading/error states, responsive layout. (S14)

H. Instagram plugin (own repo)

  • P0 [IG] Verified prerequisites (P0) · OAuth connect + token storage/refresh via task (P1) · immediate publish with checkpoint/reconcile (P2) · scheduled publish, error-class mapping, rate limits (P3).
  • P1 [IG] Carousel/reel as the API permits (P3) · no credentials in UI/logs, documented permissions and limits (P4).

I. Later plugins

P2 [LATER] AI text generation (ai_text kind: review before publishing, timeout/rate/cost limits) · TikTok after API feasibility · Reddit · further providers.

J. Quality

  • P0 [INFRA] Unit/integration/contract/authorization/deploy smoke tests; sanitizers in CI; rate/size/timeout/concurrency limits; threat-model tests and failure injection (SECURITY.md §4). (S1+, S15)
  • P1 [INFRA] Dependency/image scanning, SBOM. P2 load test.