Skip to content

DEV-2386: Document chat security, identity and V3 usage - #327

Merged
ysolodka merged 5 commits into
masterfrom
fix/DEV-2386-chat-security-docs
Nov 12, 2026
Merged

ysolodka merged 5 commits into
masterfrom
fix/DEV-2386-chat-security-docs

Conversation

@farhantariq12b

Copy link
Copy Markdown
Contributor

JIRA Issue

https://weboo.atlassian.net/browse/DEV-2386

Summary

Documents the chat security and identity model, and the V3 way to use Fliplet.Chat, in docs/API/fliplet-chat.md. This matches the fliplet-api change https://github.com/Fliplet/fliplet-api/pull/8958.

Merge only after https://github.com/Fliplet/fliplet-api/pull/8958 is live in production. The page describes behaviour that API change adds.

  • New ## Security and identity section, which covers:
    • the server decides the chat user from the data-source login;
    • only participants can see a private conversation;
    • who can create conversations, and who can change participants;
    • who can see invite codes, and which hooks app users may set;
    • integration and task tokens;
    • encryption is not access control;
    • legacy mode.
  • New "Which column identifies users" part:
    • V2 apps with a Chat component, V2 apps without one, and V3 apps;
    • a primaryKey passed to connect() is replaced by the server's value.
  • V3 usage: Fliplet.Chat.connect({ dataSourceId }), then await chat.login({}), plus:
    • the errors you get;
    • which contacts are returned;
    • no push notifications in V3;
    • offline behaviour.
  • Updated Install, connect() options, login(), logout(), contacts() and create(). Fixed the Vue chat.stream() example.
  • Frontmatter description and notes now describe the V3 path. The V3 builder catalog in Studio reads these fields.

Testing

  • npm run check:docs (strict) passes. The regenerated .well-known files are not committed, as in earlier doc PRs.

Testing notes

  1. Open the Fliplet Chat API page in the docs preview → a "Security and identity" section appears after Install, and the V3 example shows connect({ dataSourceId }) followed by chat.login({}).
  2. Read the page's short description in the docs index or search → it says V3 apps connect with a login data source, not that V3 can't use chat.

🤖 Generated with Claude Code

farhantariq12b and others added 4 commits November 5, 2026 23:35
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Deploying fliplet-cli with  Cloudflare Pages  Cloudflare Pages

Latest commit: a348622
Status: ✅  Deploy successful!
Preview URL: https://cd20e803.fliplet-cli.pages.dev
Branch Preview URL: https://fix-dev-2386-chat-security-d.fliplet-cli.pages.dev

View logs

@farhantariq12b
farhantariq12b marked this pull request as ready for review November 9, 2026 14:15

@zeryabkhan91 zeryabkhan91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review (via /fliplet-pr-review)

Review basis: subject=08d301a0342de94954b75fb319907a1b20a03464 standards=fliplet-engineering@0.18.0 revision=f4d849381caf20afa0da555c062d3b31f802471c source=fliplet-pr-review digest=sha256:40c49b60a8bd5384

Summary: Adds a "Security and identity" section, the V3 way to use Fliplet.Chat, and updates the method docs to match fliplet-api#8958.

Regression risk: Docs only, but the Studio builder catalog reads this page's frontmatter (description, notes).

Release order: fliplet-api#8958 first (live in production) → fliplet-cli#327 merged once the API is live → regenerate Studio's src/v3/ai/data/fliplet-apis.json from the live docs (npm run fetch-fliplet-apis) → fliplet-studio#9130. The three PRs don't block each other's review; this is only the order to ship them.

Findings: 1 Warning inline. Also, the page doesn't say that two rows with the same login value can't use chat: the API returns 400 for both (see the Warning on fliplet-api#8958, libs/chat-identity.js:326). Please add it to "Security and identity" once the API settles how it handles that.

CI: Green.

Comment thread docs/API/fliplet-chat.md Outdated
The server says which column identifies chat users, and `connect()` always uses its answer:

* in a V2 app with a Chat component, the component's `primaryKey` (or none, if the component has none);
* in a V2 app with no Chat component, none, so the chat runs in legacy mode;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Warning: this no longer matches the API (fliplet-api#8958, commit 13625477d).

In a V2 app with no Chat component, the API now keeps a primaryKey passed to connect() when it is the contacts data source's login column and the user is signed in to it. This line, line 50 ("so leave it out") and line 54 ("V2 apps without a Chat component run in legacy mode") say the opposite. An app that follows the doc drops to legacy IDs and stops listing its existing conversations, which is what 13625477d fixed.

Suggested change
* in a V2 app with no Chat component, none, so the chat runs in legacy mode;
* in a V2 app with no Chat component, the `primaryKey` passed to `connect()` when it is the data source's login column and the user is signed in to that data source; otherwise none, so the chat runs in legacy mode;

Lines 50 and 54 need the same change: keep "leave it out" for V3 apps and apps with a Chat component only.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified against fliplet-api 13625477d (routes/v1/apps-chat.js getComponentlessSettings, test SHOULD keep a primary key given to connect() when it is the login column, for a signed-in user only) — correct. Fixed in a348622:

  • Line 47: now says a V2 app with no Chat component uses the primaryKey when it is the login column and the user is signed in, otherwise legacy mode (your suggested wording).
  • Line 50 ("leave it out"): scoped to V3 apps and apps with a Chat component; the V2 no-component case now says to pass the login column, and that any other value is ignored (falls back to legacy).
  • Line 54 (V2 section): same correction.

Also added the deferred note to "Security and identity", since 13625477d settled it: a login value shared by two rows means neither row is a chat user (not a 400 any more), and a contact with no login value is left out of the contacts list.

…rimaryKey

A V2 app with no Chat component is no longer always legacy mode: the API
(fliplet-api 13625477d) keeps a primaryKey passed to connect() when it is the
data source's login column and the user is signed in to it. Correct the three
lines that said the opposite (identity list, "leave it out", V2 section), and
add the shared/empty login-value rule to "Security and identity".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@zeryabkhan91 zeryabkhan91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@ysolodka
ysolodka merged commit 79378c7 into master Nov 12, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants