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 per-app encryption key — 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. Each file is stored under <app_tid>/files/<tid>/<tid>.bin in the platform's binary store; the original filename is encrypted before it's saved.

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 authenticated-encryption ciphertext — 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. A per-app encryption key is minted for the new app.
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: Auto-TLS 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 → authenticated-encryption ciphertext stored in data_secret.
• User email → encrypted with the master key; only a hash is kept for lookup.
• Original filenames → encrypted into files.original_filename_encrypted; the binary store sees only UUIDs.
• ACL fields store UUIDs, not usernames or emails — a backup file does not leak PII.

24.2 Session cookie

• Authenticated-encryption ciphertext keyed by the 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 per-app encryption key, bound to app_tid. An operator with app A's key trying to decrypt an app B doc → cross-app check fails → decryption error.

24.4 Key rotation

tfl5 keys rotate-app <app_tid>
  → a new key version is minted
  → 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 an internal 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.

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

App key — Per-app encryption key. Used to encrypt sensitive fields and the original filenames of files belonging to that app.

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

Auto-TLS — On-demand TLS certificate minting: a certificate is created the first time a bound custom domain is hit.

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

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

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

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.

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

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.