On this page
MSO Cloud is the sign-in, membership, entitlement and analytics core for a family of separately deployed apps. ContentHeat, which turns trend data into ad images, videos and posts, is the first. Customers keep one credential and one admin screen; each app keeps its own repo, database, workers and release cadence.
The structure follows arc42 (sections 1-12). The diagrams use the C4 model: level 1 (system context), level 2 (containers) and one runtime sequence. The binding decision is ADR 0058. The schedule, gates and research live in the programme plan and its research appendix.
1. Introduction and goals#
Requirements. A customer works across www.msocloud.net and contentheat.younetgroup.com. The family must offer:
- one login;
- an app launcher that carries org and brand context;
- per-org app enablement by an admin;
- logout everywhere.
The design also has to admit a second and third app (proofframe, curious-kids-content-studio, already on the same host) without new identity work.
Quality goals, with weights in brackets:
| # | Quality goal | Measurable target |
|---|---|---|
| Q1 | User experience (20) | Launcher to app: 0 login prompts (J1); org and brand survive the switch in both directions (J2); invite once in MSO (J3) |
| Q2 | Security (20) | OpenID conformance suite passes before the pilot and after every issuer-library minor; no implicit account linking; ≤ 5 s logout to 401 |
| Q3 | Independent scale (15) | ContentHeat render workers (10-12 GB each) scale and deploy without an MSO release |
| Q4 | Maintainability (15) | Shared code is one versioned contract package plus design tokens; each repo keeps its own rulebook and gates |
| Q5 | Data integrity (10) | One owner per dataset; cross-system count reconciliation delta 0 over 14 days |
| Q6 | Migration safety (10) | Every step additive and reversible per org; existing ContentHeat data untouched |
Stakeholders. Org members and admins (one sign-in, one invite), platform super admins (link orgs, audited), the operator (only approver of Ask-first changes), app teams (own release cadence), and external reviewers of the authorization server.
2. Constraints#
| Constraint | Source |
|---|---|
| Two registrable domains, so no parent-domain cookie can be shared | ADR 0058 Context |
MSO sessions are 14-day Auth.js JWTs; each carries a sid whose auth_ row makes it revocable |
MSO web session callback |
| MSO web is an OIDC client of upstream directories; the issuer is a separate sidecar | ADR 0058 D2 |
| ContentHeat runs its own sign-in library with passkey and two-factor plugins and no SSO | ContentHeat auth configuration |
ContentHeat forbids framing (frame-) |
ContentHeat CSP |
| Its sign-in library refuses implicit linking to an unverified local user; ContentHeat users default to unverified | ContentHeat account-link code and schema |
| Tenant data is behind attested RLS; a satellite never reads MSO Postgres, Redis, Cube or MCP | ADR 0054 |
| One production host: Ryzen 9 9950X, 32 threads, 125 GiB, one shared reverse proxy | Host inventory 2026-11-01 |
| Live tenancy (organizations: 7, users: 24, memberships: 40, active custom domains: 2) | Production read 2026-11-01 |
3. Context and scope#
| Neighbour | Direction | What crosses |
|---|---|---|
| Org members and admins | in | One sign-in at MSO Cloud (Google, LDAP/AD, org OIDC, password, passkey, TOTP); launcher clicks |
| Org directories | in | Upstream identity; it terminates in the MSO session and reaches apps only as amr/acr |
| ContentHeat and later apps | both | OIDC tokens out; Platform API reads and content. events in; signed webhooks out |
| Data sources | in | Marketplace, marketing and social-listening data, pulled only by MSO connectors |
| Social and ad channels | in, via MSO connectors | Creatives are published by ContentHeat; their performance comes back through MSO's existing connectors |
4. Solution strategy#
| Problem | Strategy |
|---|---|
| One login across domains | MSO is the only OpenID Connect issuer; apps are relying parties |
| App enablement per org | The plugin install ledger carries plan, limits, validity and status; a satellite is a manifest kind |
| Switching apps | A launcher grid every app renders from one endpoint and one markup contract |
| Data reuse | Analytical data stays in the MSO warehouse; apps read it through a scoped API and keep their own work data |
| Independent scale and release | Each app is its own deployable on its own origin; the only shared code is a versioned contract package |
Options rejected: merging into one monorepo, an iframe or micro-frontend shell, path zones on MSO hosts, and a hosted identity vendor. Reasons are in ADR 0058, Rejected.
5. Building block view#
| Container | Responsibility | Technology |
|---|---|---|
MSO apps/ |
Login, admin, launcher, Platform API v1, the internal session route for the issuer, launch and handoff routes | Next.js 16.4, Auth.js 5. |
MSO apps/ |
OIDC issuer https:/: discovery, JWKS, authorize, token, end-session, back-channel logout |
A certified OIDC provider library, ES256 keys |
MSO apps/ |
Connectors, rollups, platform_ webhooks |
BullMQ on Redis |
| MSO Postgres | Warehouse (three data planes), yng_, issuer key table |
Postgres 16, FORCE RLS |
| MSO Redis | Queues, cache, issuer grants under their own key prefix | Redis |
ContentHeat web |
Relying party, provisioning and webhook receivers, back-channel logout receiver, creative workflow UI | Next.js 16.4, generic OAuth provider |
ContentHeat worker, worker- |
AI generation, ffmpeg and Chromium rendering; scale independently | pg-boss on Postgres 18 |
| ContentHeat Postgres, RustFS | Orgs, brands, RBAC, briefs, approvals, trend-feed projection; generated assets | Postgres 18 with RLS, S3-compatible store |
Shared code is published to a private package registry under the younetgroup scope, as @younetgroup/platform-contract (Zod schemas, CONTRACT.md, the vi copy bundle, the J1-J6 conformance specs) and @younetgroup/design-tokens (CSS variables). Minor versions are additive; a breaking change gets a new major kept 90 days beside the old one. ContentHeat's repository moved to younetgroup/content-engine-platform on 2026-11-01, so one package ACL and one CI identity cover both apps. Its Docker build reads the registry with a read:packages token passed as a BuildKit secret, never as a build arg.
6. Runtime view#
6.1 Launcher to app with zero prompts (J1)
The authorize step always runs on the issuer host, because the issuer's interaction cookie is host-scoped. A user on a tenant host (acme.msocloud.net) or a custom domain therefore crosses once through a single-use, 60-second handoff token bound to the session id (sid). The token is built on the existing magic-link mechanism, and an audit row records the origin host.
6.2 Cold deep link and white-label orgs
- A user opens a deep link into ContentHeat for an org and brand, with no app session.
- The app redirects to
/oauth2/authwithprompt=noneand an org hint. - If the issuer host already holds a session, the code returns with no UI.
- If not, the issuer renders that org's branded login (the existing branded login of ADR 0045) on
msocloud.net. - The user signs in once and returns to the deep link.
White-label orgs use the same flow; their browsers pass through msocloud.net redirects for the sign-in step. Home-realm discovery (email to org) and an app host on the customer's own domain are directions: Future direction.
6.3 Logout everywhere
- Sign-out in any app calls the issuer's
end_sessionwithid_token_hint. - The issuer sets
auth_sessions.revoked_atfor thesid. - It posts an OIDC Back-Channel Logout
logout_tokento every client holding thatsid. - Each app verifies the token against the issuer JWKS (
iss,aud,iat,events,jtireplay set) and deletes its sessions bysid, falling back tosub. - The post-logout redirect clears the MSO cookie.
ContentHeat sessions are DB rows with the cookie cache off, so the next request returns 401. The acceptance bound is 5 s (journey J5). Front-channel logout is not used, because cookie partitioning breaks it.
6.4 Data pull and change events
- Org provisioning. Users and memberships are created just-in-time from ID-token claims at each login. The app can read the org, its brands and members from the Platform API with a client-credentials token.
- Changes. MSO writes
org.app.changed,membership.changed,user.disabledandtrends.updatedtoplatform_outboxin the same transaction as the change. A worker sweep delivers them as HMAC-SHA256-signed webhooks withX-MSO-Event-Id, retrying with backoff: Platform API and events. - Trend reads. ContentHeat reads
/api/platform/v1/orgs/{id}/social/trends(+/counts) with an access token that carries oneorg_idand theplatform:social.readscope. - Lineage. When ContentHeat publishes a creative it emits
content.published(asset id, channel post id, brand, campaign) to MSO. - Reconciliation.
verify:dataasserts the trend counts endpoint against the rows the list returns; the app compares its projection per brand against that endpoint.
7. Deployment view#
| Node | Runs |
|---|---|
| CDN and DNS | DNS and CDN for msocloud. and *.; cache bypass for / and / |
| Reverse proxy (one per host) | Routes PathPrefix(/ on the platform host to msocloud-; the rest to apps/ |
Stack msocloud- |
web, worker, msocloud-, Postgres 16, Redis (issuer grants under their own prefix), RustFS |
Stack ce- |
web, worker, worker-media, landing, Postgres 18, RustFS |
Keys and secrets. Issuer signing keys (ES256, overlapping rotation) and the ContentHeat client key live in yng_auth, envelope-encrypted with the existing secret-encryption key. The issuer connects as a dedicated role yng_idp that can only SELECT the key table. It never holds the web app's DB URL or SESSION_SECRET, and reads the MSO session only through GET /api/internal/idp/session. That route uses bearer authentication and returns {sub, sid, amr, auth_time, email, email_verified}.
Deploys. Each repo deploys on its own: MSO through ./scripts/start-prod.sh (the issuer sidecar with its --with-idp flag), ContentHeat through its own start-prod.sh.
8. Cross-cutting concepts#
8.1 Identity and claims
The ID token carries iss, sub, aud, exp, iat, auth_time, nonce, sid, amr[], acr, email, email_verified, name, locale. Under https://msocloud.net/claims/ it adds:
orgs: [{id, slug, name, role, brand_ids|null, apps[]}], capped at 50; beyond that,orgs_truncated: trueand the app calls/me;active_org,active_brandandsuper_admin.
An access token is an RFC 9068 at+jwt with aud=https://msocloud.net/api/platform, exp ≤ 10 min and exactly one org_id. email_verified derives only from a new users.email_verified_at, set by magic link, a Google identity or an LDAP bind. App-specific roles stay in the app. The role floor maps owner→owner, admin→admin, editor→creator and viewer→viewer. App admins may add finer roles within that floor.
8.2 Tenancy and entitlement
"Org X has app Y on plan Z" is one row in org_plugin_installations. The table carries plan, limits, valid_to and status, and a trial is just a valid_to value. The plugin manifest has kind:'satellite' with clientId, launchUrl, scopes and planIds ; the launch URL is overridable per environment. Entitlement is checked twice:
- at login, from the
apps[]claim; - on the server, through
/orgs/{id}/entitlements, with a 5-minute cache that webhooks invalidate.
The issuer refuses a client-credentials token for an org without the app installed, so enforcement sits at the data, not in navigation (§47). The launcher (GET /api/platform/v1/me/launcher) returns one tile per app for the active org, in state enabled, not_enabled or expired; the app is opt-in per org. Seat assignment is not in the schema: Future direction.
8.3 Data ownership
Each dataset has one owner, following data mesh's "source-aligned" ownership.
| Data | Owner | Others get it by |
|---|---|---|
| Social trends (3rd-party market-intel plane), marketing and marketplace performance | MSO warehouse | Platform API v1, one scope per plane; trends. webhooks |
| The shared social trend feed: synced once in MSO Cloud, the same rows for every org | MSO warehouse, shared dataset plane | The four social/ routes; an app keeps a projection and pulls on change |
| Dashboards, charts, AI analysis | MSO | Deep link from any app's launcher to the MSO dashboard; never an iframe |
| Briefs, generated assets (RustFS), render jobs, brand kits, approvals, schedules | ContentHeat | Not shared; content. events carry ids only |
| Performance of a published creative | MSO | MSO's ad and social connectors pull it and attribute it to the creative via content. lineage; ContentHeat never pushes numbers |
The social trend feed is synced in MSO Cloud: one vendor account, one session, one sync for every org. ContentHeat no longer calls the vendor; it pulls the feed through the Platform API (Platform API and events) and keeps a local projection, so a render never blocks on MSO uptime. The projection keeps the source key it already uses (ADR 0061 D7); no new mso-social key is introduced.
- Pull. Per linked org the app reads the feed state and stores that org's grant (enabled, slices) with the time MSO confirmed it. Each slice any org was granted is fetched once with
If-None-Matchand replaced in one transaction, only when the answer'srevisionis higher than the stored one; history windows work the same way. A failed or partial pull changes nothing. Triggers are thetrends.updatedwebhook and an hourly reconciliation. - Grants and the 3 h lease. Every local read is scoped by the org's stored grant. A grant MSO denied (
enabled: false, 403, or a refused token) is removed at once. A grant MSO has not confirmed for 3 hours stops being honored until the next confirmation. An org not linked to MSO has no grant and no feed. Content may be stale; authorization may not. - Owner. MSO Cloud holds the dataset, the spam-review decisions and the recipient list. The app's own tables are its projection only.
8.4 Security controls and the standard each follows
| Control | Standard |
|---|---|
| Authorization code with PKCE S256 for every client | OIDC Core 1.0; RFC 7636; RFC 9700 (OAuth 2.0 Security BCP) |
| Client authentication by signed JWT assertion, no shared client secrets | RFC 7523 (private_) |
JWT access tokens with a fixed aud and one org |
RFC 9068; RFC 8707 resource indicators |
| Exact redirect URIs, static first-party clients, dynamic registration off | RFC 9700 §2.1, §4.1 |
| Refresh-token rotation with family revocation | RFC 9700 §4.14 |
| Server-side session id, revocable | OWASP ASVS V3 (session management) |
| Logout to every app | OIDC Back-Channel Logout 1.0 |
| Account linking only with proof of both accounts; the MSO provider is never trusted for implicit linking | OWASP ASVS V2; the library's verified-email default |
| Signed, idempotent webhooks | HMAC-SHA256 with event-id replay protection |
| Library patch SLA of 7 days for the issuer library, the sign-in libraries and the JOSE library | Operating control |
9. Architecture decisions#
| Decision | Summary |
|---|---|
| D1 | Platform core plus satellites, each app on its own origin; no path zones, iframes or shared secrets |
| D2 | One issuer, https:/, served by a certified sidecar |
| D3 | Server-side session id and revocation table first |
| D4 | Tenant-host users reach apps with zero prompts through a single-use handoff |
| D5 | Verified email recorded in MSO |
| D6 | Claim contract: orgs[] in the ID token, one org per access token |
| D7 | Entitlement reuses the plugin install ledger |
| D8 | Org pushed on install, users just-in-time, changes by signed webhooks |
| D9 | Linking an existing app account needs proof of both accounts |
| D10 | Platform API v1, one scope per data plane |
| D11 | Logout everywhere through back-channel logout |
| D12 | Shared contract and design tokens as versioned packages |
| D13 | White-label orgs: branded login on the issuer; an app host on the customer's domain follows |
| D14 | Moving the web sign-in library is a separate decision, ADR 0059 (gate 2027-Q2) |
| D15 | Data ownership: analytics in MSO, creative and workflow data in the app (section 8.3) |
All of these are recorded in ADR 0058. D15's source key is amended by ADR 0061 D7. The ContentHeat side is recorded as its decision D225 (relying party of MSO Cloud).
10. Quality scenarios#
| Scenario | Response | Measure |
|---|---|---|
An admin signed in at acme. clicks the ContentHeat tile |
App opens on the same org and brand | 0 login prompts (J1) |
| An MSO admin removes a member | Webhook plus next-login claims remove access in the app | Member absent from the next claims |
| A user signs out in either app | Every app tab is signed out | ≤ 5 s to 401 (J5) |
| The issuer library releases a minor version | Conformance suite reruns before upgrade | OpenID Basic, Config, RP-Initiated and Back-Channel Logout profiles pass |
| The issuer is down | Existing app sessions continue; new logins fail closed with a Vietnamese message | No data exposure; recovery by router label |
| Trends change in MSO | trends. refreshes the app projection |
14-day per-brand count delta 0 |
| A second app joins | Satellite kit: manifest, client, relying-party wiring, conformance specs | ≤ 2 engineer-weeks |
Acceptance for a linked org. All of these hold:
- a real admin performs journeys J1, J2, J3 and J5 (the specs ship in
@younetgroup/platform-contract); - 0 users are left unmatched;
- the 14-day trend-count reconciliation delta is 0;
- logout takes <= 5 s.
11. Risks and technical debt#
CI runs pnpm --filter @yng/idp test:conformance after unit tests. This separate integration tier starts the issuer on loopback with an in-memory adapter; the pure unit configuration excludes it.
| Risk or debt | Mitigation |
|---|---|
| Operating an identity provider (frequent library advisories) | Configuration-only use of a certified library; 7-day patch SLA; issuer conformance; external review of the authorization server before the second customer org |
| Identity split-brain: a role removed in MSO stays live in an app | No app-local password for linked users; claims refreshed at every login; webhooks; back-channel logout; trend-count reconciliation in verify:data |
| The handoff route becomes a session-minting hole | Single-use, 60-second, sid-bound token; same-site check; audit row; rate limit; operator review before merge |
| Wrong account or org link | Credential proof; super-admin-only org links; per-org unlink; rehearsal on a DB clone |
White-label users see msocloud. in the address bar during sign-in |
Branded login on the issuer; an app host on the customer's own domain removes it |
MSO still runs Auth.js 5. |
ADR 0059 decides the move (gate 2027-Q2); the issuer contract is frozen so apps do not notice |
| The vendor's terms on storing and redistributing the trend data are open | The feed goes only to orgs that hold it, so the recipient list is a written fact; one MSO sync replaces ContentHeat's own vendor connector (ADR 0061) |
| Contract package sits on a different GitHub owner than ContentHeat | Move the ContentHeat repo into younetgroup; token as BuildKit secret meanwhile |
12. Glossary#
| Term (en) | Vietnamese | Meaning |
|---|---|---|
| Issuer / IdP | Nơi cấp danh tính | The one service that signs ID and access tokens: https:/ |
| Relying party (RP) | Ứng dụng tin cậy IdP | An app that accepts the issuer's tokens instead of keeping its own passwords |
| Satellite app | Ứng dụng vệ tinh | An app with its own repo, database and deploy that signs in through MSO |
| Entitlement | Quyền dùng ứng dụng | Whether an org has an app, on which plan, until when |
| Launcher | Trình mở ứng dụng | The grid of enabled apps shown in every app's top bar |
| Handoff token | Token chuyển phiên | Single-use, 60-second token that carries a session from a tenant host to the issuer host |
| Back-channel logout | Đăng xuất qua kênh sau | Server-to-server logout message from the issuer to each app |
| Step-up | Xác thực tăng cường | A fresh second factor asked before a sensitive action |
| Data plane | Mặt phẳng dữ liệu | One of three datasets that never mix: 1st-party marketplace, 1st-party marketing, 3rd-party market-intel |
| Projection | Bản chiếu dữ liệu | An app's read copy of data another system owns, reconciled against the owner |
| Grant | Quyền đọc đã cấp | An org's stored right to read the trend feed's slices in an app; lapses after 3 hours without MSO confirming it |