End-user guide for tafalo5

2. Model & roles

Everything in tafalo5 revolves around four objects and a single permission check. Understanding the diagram below covers ~90% of platform usage.

platform (system-wide, singleton)
 ├── user        (account; shared across all apps)
 ├── group       (global group, peer of app)
 └── app         (your workspace — literally called "app")
      ├── role         (in-app role)
      ├── resource     (data type / schema)
      │    └── doc     (a concrete record)
      └── folder/file  (binary store)

2.1 Roles you may encounter

3. Quick start — 5 steps

1. Register an account (username, email, password ≥ 6 chars).
2. Sign in — the server issues a 24-hour session cookie.
3. Create an app — you become its sole app.managers entry.
4. Bind a domain (optional) — add A + TXT records to your DNS.
5. Create your first resource and doc — your data is online.

4. App

An app is an independent workspace with its own schema, data, users, and any number of bound domains.

• Each app has its own app_key minted by KMS — sensitive fields are encrypted with it.
• The creator becomes app.author and the only entry in app.managers.
• Your maximum number of apps is bounded by license.user_max_apps (see §23).
• Ownership can be transferred to another user.

5. Resource

A resource is a schema — you declare fields, validators, and per-field sensitivity (public / private / secret). When a user creates a doc, the platform:

• Validates data against each field's rules;
• Runs the before_create DSL/hooks;
• Generates doc.tid and stamps doc.author;
• "Freezes" the doc's ACL from the resource.acls template;
• Encrypts every field whose sensitivity != "public" with the app_key.

6. Doc

A doc is one concrete record of a resource. After creation its ACL is immutable — nobody can change it directly. Only app.managers can re-apply the template in bulk via POST /data/reset/<resource_id>.

7. Files & folders

Files and folders are each app's binary store. A folder can carry a folder.acls template that is stamped onto child files/subfolders at creation time. Files live on S3 under <app_tid>/files/<tid>/<tid>.bin; the original filename is encrypted before it hits the database.

8. Domain

A domain is bound to an app after DNS verification succeeds. An app can host many domains, and each can have its own theme, language, noaccess list, and URL routes.

9. Groups & roles

A group is global (peer of an app). A role exists inside one app. Both can appear in any ACL list.

• G_author = every signed-in user (implicit).
• anonymous = every visitor (implicit).
• G_<uuid> = a global group you created.
• [<uuid>] = an in-app role — note the square brackets.

10. Workflow — Register & sign in

10.1 Register

Endpoint: POST /reg with body {username, password, re_password, email}.

• Username must be unique; email must be unique.
• Password must be ≥ 6 characters and match re_password.
• The email is encrypted with the master key before storage; only a hash is kept for lookup.
• Per-IP rate limiting via the TFL5_RATE_LIMIT_REG env var.

10.2 Sign in

Endpoint: POST /login with {username, password}. The server issues an _token cookie:

• Value is AEAD ciphertext (ChaCha20-Poly1305) — not readable client-side.
• Lifetime 24h, with rolling refresh on every authenticated request.

10.3 Change password

Self-reset: POST /user/resetp {old_password, new_password}. Wrong old password → 400. After the change, existing sessions can be invalidated if the operator has enabled token-version bumping.

10.4 Sign out

POST /logout — the server sets the cookie to empty with Max-Age=0. Then POST /user returns {isSignout: true}.

10.5 Delete account

Self-delete succeeds only when user.app_count == 0. If you still own apps, you must delete or transfer them first.

11. Workflow — Create an app

1. Prerequisite: Your account is in platform.designers (default is G_author, so every signed-in user can create apps).
2. Send POST /app/update with {data: {name, description, ...}}.
3. The server generates app.tid, sets app.author = you, adds you to app.managers.
4. KMS mints an app_key, stored in the app_keys table.
5. user.app_count is incremented by 1.

12. Workflow — Bind a custom domain

Convention: verify-then-save. A domain row is only persisted with active=true after DNS proof passes.

1. Preview: POST /app/domain/preview {app_tid, domain} — the server returns the A-record target and a verify token.
2. Configure DNS:
   • A: <domain> → platform.domain_a_record_target.
   • TXT: _tfl5.<domain> → the verify_token value.
3. Verify & save: POST /app/domain/add {app_tid, domain, verify_token}. Both DNS records correct → a domains row is inserted with active=true.
4. TLS: Caddy on-demand mints the certificate on the first request to that domain.
5. Weekly re-verify: The platform re-checks DNS periodically. Four consecutive failures (~30 days) flip active=false and notify you.

13. Workflow — Design a resource

Only AppDes (members of app.designers) can create resources.

POST /app/resource/add
{
  "data": {
    "ma": "post",            // unique code within the app
    "name": "Blog post",
    "fields": [
      { "field": "title",   "type": "text",  "sensitivity": "public",  "validator": ["required","minlen:3"] },
      { "field": "body",    "type": "html",  "sensitivity": "public" },
      { "field": "secret",  "type": "text",  "sensitivity": "private" }
    ],
    "acls": {
      "editors":   ["@author"],
      "readers":   [],            // [] = public
      "deletable": ["@author"]
    },
    "sharing": true
  }
}

14. Workflow — Doc CRUD

14.1 Create a doc

POST /data/add/<resource_id>
{ "data": { "title": "Hello world", "body": "..." } }

14.2 List & filter

POST /data/gets/<resource_id>
{
  "filter_rules": [
    { "field": "title", "op": "contains", "value": "hello" }
  ],
  "skip": 0,
  "limit": 20         // capped at 100
}

The query layer automatically folds ACL conditions into the SQL — you only receive docs you're allowed to read. Docs reached through a share are field-projected by share.fields.

14.3 Update & delete

• POST /data/edit/<resource_id>/<doc_id> — partial merge of data, appends to histories.
• POST /data/del/<resource_id>/<doc_id> — soft delete (sets deleted_at).

14.4 Bulk ACL reset

AppMgr only: POST /data/reset/<resource_id> {filter_rules}. The server recomputes editors/readers/deletable/noaccess for each matching doc from the current resource.acls template, preserving author.

15. Workflow — Upload & download files

1. Init: POST /app/file/upload-init {filename, size} → returns {file_tid, upload_url} (presigned PUT, 10-minute TTL).
2. PUT to S3 directly from the client (bypasses the server).
3. Finalize: POST /app/file/finalize {file_tid} — the server HEADs the object, verifies size, writes the row, charges quota.
4. Download: GET /file/<file_tid> → 302 redirect to a signed S3 URL (5-minute TTL).

16. Workflow — Sharing

Sharing is read-only at the doc level. You cannot share folders, files, or whole resources. Editing and deletion still go through the formal ACL.

16.1 Mint for a specific user

POST /share
{ "app_id": "...", "resource_id": "post", "doc_id": "...",
  "target": "u_bob", "fields": null }

16.2 Mint a public link

POST /share
{ ..., "target": "anonymous", "generate_token": true,
  "expires_at": 1893456000000 }
=> { "share": {...}, "token": "<plaintext_one_time>",
     "url": "https://acme.com/?_share=<plaintext>" }

16.3 Field filter

fields: ["title","summary"] → the recipient only sees those two fields. Other fields are stripped; metadata (tid, author, created_at...) is always shown. ACL fields are always hidden from share-based access.

16.4 Revoke

DELETE /share/<share_tid> — sets revoked_at. The row is kept for audit. Automatic cleanup after 12 months.

16.5 Interaction with other rules

• noaccess beats share. An app with noaccess: ["anonymous"] denies even a valid public token.
• resource.sharing = false is a kill switch: new shares get 400; existing shares are temporarily ignored (and reactivated if the flag is flipped back).
• Soft-deleted doc → all of its shares stop working (every check injects deleted_at = 0).

17. Workflow — Multiple domains, one app

• Bind both acme.com and acme.vn to the same app — shared data, different theme/language.
• intranet.acme.com with noaccess: ["anonymous"] — public is locked out.
• Per-domain url_routes: "/posts/:slug" → server-side render with the doc preloaded.

18. Access control — the permission set

On every request the server builds a permission set:

permission_set = [
  user.tid,                                            // bare uuid
  ...user.groups.map(g => g.tid),                      // "G_<uuid>"
  ...user.roles_in_current_app.map(r => "[" + r.tid + "]"),
  is_authenticated ? "G_author" : "anonymous"
]

A request "passes" a gate when permission_set ∩ gate_field ≠ ∅ — i.e., they share at least one element.

19. ACL fields

20. noaccess cascade

platform.noaccess  → denies: app, group, user (everything below)
app.noaccess       → denies: resource, doc, file, folder, role
resource.noaccess  → denies: docs of that resource
folder.noaccess    → denies: file + subfolder inside (recursive)
doc/file/role/group/license.noaccess → leaf (the entity itself only)

deny_set when checking entity E:
  deny_set = platform.noaccess
          ∪ A.noaccess              (E belongs to app A)
          ∪ R.noaccess              (E belongs to resource R)
          ∪ F.ancestors.noaccess    (E is a file/folder, recursive)
          ∪ E.noaccess

permission_set ∩ deny_set ≠ ∅  →  DENY immediately, no further checks.

21. Templates & @author

Three places carry templates: resource.acls, folder.acls, app.acls. When a child entity is created, the template is applied overwrite-style (not union) to the child's ACL fields, and the pseudo-token @author is replaced with the creator's UUID.

resource.acls.editors = ["@author", "[t_editor_role]"]

→ alice (u_alice) creates doc d1:
   d1.author  = "u_alice"
   d1.editors = ["u_alice", "[t_editor_role]"]

During reset, the server re-substitutes @author using the stored doc.author — the author never changes.

22. Who can change ACLs?

23. Platform rules — Quotas & licenses

A license is a "plan" attached to a user or to an app and defines hard ceilings.

23.1 Quota fields

23.2 Enforcement algorithm

can_create_app(user):
  permission_set ∩ platform.designers ≠ ∅
  AND user.app_count < (user.override_max_apps ?? license.user_max_apps)

can_upload_file(user, app, size):
  not (user in app.noaccess cascade)
  AND permission_set ∩ app.developers ≠ ∅
  AND user.used_storage + size ≤ (override ?? license.user_max_total_storage)
  AND app.used_storage  + size ≤ app_license.app_max_storage

23.3 Over-quota behaviors

• block_upload — new uploads are rejected; reads still work.
• read_only — every POST CRUD is rejected.
• suspend_domain — the domain returns 503 (v2).

23.4 Upgrades & overrides

Operator-only (CLI). Examples:

tfl5 user license <user_tid> pro
tfl5 user override <tid> --max-apps 100

24. Platform rules — Security & encryption

24.1 Encryption at rest

• Doc fields marked private/secret → ChaCha20-Poly1305 AEAD ciphertext in data_secret (BYTEA).
• User email → encrypted with the master key; only a hash is kept for lookup.
• Original filenames → encrypted into files.original_filename_encrypted; S3 sees only UUIDs.
• ACL fields store UUIDs, not usernames or emails — a database dump does not leak PII.

24.2 Session cookie

• AEAD ciphertext keyed by platform_passphrase (server-side).
• HttpOnly Secure SameSite=Lax
• Random nonce per encrypt → two consecutive logins produce two different cookies.
• 24-hour rolling lifetime; optional IP-binding (config) to invalidate cookies stolen from another IP.

24.3 Cross-tenant isolation

Each app has its own app_key; the AAD in the AEAD is bound to app_tid. An operator with app A's key trying to decrypt an app B doc → AEAD AAD failure → decryption error.

24.4 Key rotation

tfl5 keys rotate-app <app_tid>
  → KMS mints version 2
  → background job re-encrypts each doc
  → 30-day grace period before v1 is destroyed

24.5 Audit log tamper detection

Every audit row is hash-chained to the previous one. tfl5 audit verify-chain --last 30d spots tampering by detecting a broken hash.

25. Platform rules — Usage rules

• TLS required. Plain HTTP is redirected to HTTPS.
• Rate limiting on /reg and /share/claim, per IP.
• Consistent response format: success {result:true, ..., timestamp}; error {result:false, msg:<string|array>}.
• No filtering on sensitive fields. Filter rules must target fields with sensitivity: "public"; violations return 400.
• No mock data in dev. Every test goes against real data so that real constraints are exercised.
• UI strings. The platform default is English. Tenants can override via the /cpanel/lang bundle.

26. Platform rules — Data lifecycle

27. Hooks & validators

Designers wire automated behavior into each resource:

27.1 Field validators

fields: [
  { "field": "title", "validator": ["required", "minlen:3"] }
]

27.2 DSL rules

before_create.set: {
  "data.slug": "lower(replace(data.title, ' ', '-'))"
}

before_delete: [
  { "when": "doc.data.status == 'published'",
    "deny": "Cannot delete a published post" }
]

27.3 Webhooks

after_create.call_webhook:  "notify_slack"
before_create.call_webhook: { name: "validate_invoice", on_fail: "abort" }

• Hooks are pushed onto a NATS queue; a worker delivers each one with an HMAC signature.
• on_fail: "abort" + the webhook returning {result:false} aborts the create.
• Up to 3 exponential-backoff retries.

28. SDK & integration

Three distribution paths:

Browser

<script src="/sdk.js"></script>
<script>
  const tfl5 = new TFL5();
  await tfl5.login(username, password);
  const posts = await tfl5.resource("post").list({ filter_rules: [], limit: 20 });
</script>

Node (server-to-server)

import { TFL5 } from "@tfl5/sdk";
const tfl5 = new TFL5({ host: "https://acme.com", appId: "a_xxx",
                        token: process.env.TFL5_TOKEN });
await tfl5.user();

Anonymous share claim

const tfl5 = new TFL5();
await tfl5.claimFromUrl();  // reads ?_share=... + calls /share/claim
const doc = await tfl5.resource("post").get(docId);  // auto-attaches X-Share-Token

29. Common errors

30. FAQ

31. Glossary

ACL — Access Control List. A token list that decides who can do what to an entity.

AEAD — Authenticated Encryption with Associated Data. tafalo5 uses ChaCha20-Poly1305.

App — An independent workspace with its own schema, data, and users.

App key — A KMS-managed encryption key unique to one app.

app_tid / doc.tid — The unique identifier (UUID) of the corresponding entity.

Caddy — Reverse proxy with auto-TLS; asks tfl5 via /internal/caddy/ask before minting a cert.

Cascade — A parent-tier noaccess propagating down to every child entity.

Cell — A deployment unit (its own Postgres + storage). v1 ships with the single cell default.

data_indexed / data_secret — Twin columns holding plaintext public fields (JSON) and encrypted sensitive fields (BYTEA).

Doc — A concrete record of one resource. ACL is immutable after creation.

DSL hook — A declarative rule (set/when/deny) that runs around doc CRUD.

G_author — The implicit group containing every signed-in user.

KMS — Key Management Service; issues app_keys and handles rotation / soft-delete.

License — A plan attached to a user or app that determines quotas and features.

NATS — Message queue used for audit, webhooks, and search indexing.

Permission set — The list of tokens a caller carries within one request.

Platform — The system-wide singleton config row.

Resource — Schema + ACL template + hooks for one kind of doc.

Role — A per-app role (its token is wrapped in square brackets).

Sensitivity — A field's classification: public / private / secret.

Share — A record granting read access to one doc for one target (user / group / role / anonymous).

Soft delete — Setting deleted_at > 0; the default filter hides such entities.

Token (ACL) — One identifier string: <uuid>, G_<uuid>, [<uuid>], G_author, or anonymous.

verify-then-save — The domain-binding principle: insert a row only after DNS proof passes.