@pinooxhq/auth

Auth for Pinoox themes — configured in PHP, zero hardcoding in the SPA.

Token storage, authorized HTTP, me() / logout, and login redirects for Vue, React, and Svelte. Values come from window.__PINOOX__.auth (published by auth.client in app.php).

Contents

1. Schematics & how it works ← start here
2. Setup guide — Independent
3. Setup guide — SSO
4. Platform variant
5. Quick theme module
6. Why auth.client?
7. App configuration reference
8. Theme integration
9. HTTP, redirects, adapters
10. API reference
11. Vite

1. Schematics & how it works

Two layers always work together:

| Layer | Where | What it controls | | ----- | ----- | ---------------- | | transport | app.php | Which app owns users / JWT secret / token key on the server | | auth.client | app.php → __PINOOX__.auth | What the SPA knows: strategy, login URL, API endpoints |

Independent mode

Each app logs users in by itself. Tokens are not shared.

flowchart LR
  User --> Shop
  User --> CRM
  Shop -.- Sown[own login + token]
  CRM -.- Cown[own login + token]

How it works

1. app.php: auth.mode + auth.key + client => true (no transport).
2. Strategy is local — login UI lives in this app.
3. Login issues a JWT stored under that app’s auth.key.
4. me / logout hit this app’s API only.

SSO mode (one login + dependents)

One app (com_pinoox_account) is the login. Shop and CRM reuse the same session.

flowchart LR
  Shop -->|no token| Account
  CRM -->|no token| Account
  Account -->|shared token| Shop
  Account -->|shared token| CRM

How it works

1. Account owns users + auth.key (local login).
2. Shop / CRM: transport.user => com_pinoox_account + strategy: remote.
3. Guest → redirect to Account → login → back with ?redirect=.
4. Same browser key unlocks every dependent app.

| | Account | Shop / CRM | | - | ------- | ---------- | | Login | Yes | No | | Token key | Defines it | Shared via transport | | Strategy | local | remote |

2. Setup guide — Independent

Goal: Shop has its own login. CRM is unrelated (or also independent with a different key).

Step 1 — app.php

// apps/com_pinoox_shop/app.php
return [
    'package' => 'com_pinoox_shop',
    // … theme, router, …

    // no 'transport' → local users + local auth

    'auth' => [
        'mode' => 'jwt',
        'key' => 'pinoox_shop_auth',
        'lifetime' => 30,
        'lifetime_unit' => 'day',
        'client' => true,
    ],
];

php pinoox pinker:rebuild com_pinoox_shop -n

Step 2 — Theme auth module

cd apps/com_pinoox_shop/theme/default
npm install @pinooxhq/auth axios

// src/utils/auth/index.js
import axios from 'axios'
import { defineStore } from 'pinia'
import { createAuth, createHttp } from '@pinooxhq/auth'
import { createPiniaAuthStore } from '@pinooxhq/auth/vue'

export const auth = createAuth({ debug: import.meta.env.DEV })
export const http = createHttp({ auth, axios })
export const useAuthStore = createPiniaAuthStore(defineStore, 'auth')

Step 3 — Login page

<script setup>
import { http, useAuthStore } from '@/utils/auth'
import { useAuthRedirect } from '@pinooxhq/auth/vue'

const store = useAuthStore()
const { redirectBack } = useAuthRedirect()

const onLogin = async () => {
  const { data } = await http.post('auth/login', { username, password })
  const body = data?.data ?? data
  store.login(body.token, body.user)
  redirectBack()
}
</script>

Step 4 — Guard

import { useAuthStore } from '@/utils/auth'

export async function authGuard(to, _from, next) {
  const store = useAuthStore()
  store.syncTokenFromStorage()
  if (!store.isAuth) await store.canUserAccess(true)
  if (to.meta.requiresAuth && !store.isAuth) {
    return next({ name: 'login', query: { redirect: to.fullPath } })
  }
  next()
}

Checklist

• [ ] auth.mode + auth.key on this app
• [ ] auth.client => true
• [ ] Login UI in this theme
• [ ] Do not set strategy: remote
• [ ] Twig: pinoox_bootstrap before vite_tags

3. Setup guide — SSO

Goal: Account is the only login. Shop and CRM reuse one session.

Step 1 — Provider (com_pinoox_account)

// apps/com_pinoox_account/app.php
'auth' => [
    'mode' => 'jwt',
    'key' => 'pinoox_ecosystem', // shared by every dependent
    'client' => true,            // local strategy
],

Account theme: normal local login (same as Independent Step 3), then redirectBack() so ?redirect= returns the user to Shop/CRM.

php pinoox pinker:rebuild com_pinoox_account -n

Step 2 — Dependent Shop

// apps/com_pinoox_shop/app.php
'depends' => ['com_pinoox_account'],

'transport' => [
    'user' => 'com_pinoox_account', // inherit users + JWT secret + key
],

'auth' => [
    'client' => [
        'strategy' => 'remote',
        'loginUrl' => '/account/login',
        'baseUrl' => '/account/api/v1',
        'endpoints' => [
            'login' => 'auth/login',
            'logout' => 'auth/logout',
            'me' => 'auth/get',
        ],
    ],
],

Step 3 — Dependent CRM (same pattern)

// apps/com_pinoox_crm/app.php
'depends' => ['com_pinoox_account'],
'transport' => ['user' => 'com_pinoox_account'],
'auth' => [
    'client' => [
        'strategy' => 'remote',
        'loginUrl' => '/account/login',
        'baseUrl' => '/account/api/v1',
        'endpoints' => [
            'me' => 'auth/get',
            'logout' => 'auth/logout',
        ],
    ],
],

php pinoox pinker:rebuild com_pinoox_shop -n
php pinoox pinker:rebuild com_pinoox_crm -n

Step 4 — Theme on each dependent

Same utils/auth as Independent — no hardcoded key. createAuth() reads remote settings from __PINOOX__.auth.

export const auth = createAuth({ debug: import.meta.env.DEV })
export const http = createHttp({ auth, axios })
export const useAuthStore = createPiniaAuthStore(defineStore, 'auth')

Guard — redirect to Account when guest:

import { auth, useAuthStore } from '@/utils/auth'

export async function authGuard(to, _from, next) {
  const store = useAuthStore()
  store.syncTokenFromStorage()
  if (!store.isAuth) await store.canUserAccess(true)
  if (to.meta.requiresAuth && !store.isAuth) {
    auth.redirectToLogin() // → /account/login?redirect=…
    return
  }
  next()
}

Do not build a login form on Shop/CRM for SSO — only Account has the form.

Checklist (dependent)

• [ ] transport.user → com_pinoox_account
• [ ] auth.client.strategy = remote
• [ ] loginUrl = /account/login
• [ ] baseUrl + endpoints for me / logout
• [ ] Do not set a different auth.key (unless you want a separate session)
• [ ] Pinker rebuild after app.php changes

Side-by-side

| | Independent | SSO | | - | ----------- | --- | | Example | Shop alone; CRM alone | Account ← Shop, CRM | | transport.user | — | com_pinoox_account | | Login UI | Each app | Account only | | Browser key | Per app (pinoox_shop_auth, …) | One key (pinoox_ecosystem) | | auth.client | true | map with strategy: remote |

4. Platform variant

Same idea as SSO, but the login owner is the platform auth app (Manager), not Account. Use for admin tools that must not share the customer Account session.

flowchart LR
  CRM -->|no token| Manager
  Inventory -->|no token| Manager
  Manager -->|one token| CRM
  Manager -->|one token| Inventory

// dependent admin app
'transport' => ['user' => 'platform'],
'auth' => [
    'client' => [
        'strategy' => 'remote',
        'loginUrl' => '/manager/login',
        'baseUrl' => '/crm/api/v1',
        'endpoints' => [
            'me' => 'auth/get',
            'logout' => 'auth/logout',
        ],
    ],
],

| transport.user | Auth / users come from | | ---------------- | ---------------------- | | omitted / local | This app only (independent) | | 'com_pinoox_account' | Account SSO | | 'platform' | Platform / Manager SSO |

5. Quick theme module

Same for all topologies — only __PINOOX__.auth changes.

cd apps/com_pinoox_shop/theme/default
npm install @pinooxhq/auth axios
php pinoox pinker:rebuild com_pinoox_shop -n

src/utils/auth/index.js:

import axios from 'axios'
import { defineStore } from 'pinia'
import { createAuth, createHttp } from '@pinooxhq/auth'
import { createPiniaAuthStore } from '@pinooxhq/auth/vue'

export const auth = createAuth({ debug: import.meta.env.DEV })
export const http = createHttp({ auth, axios })
export const useAuthStore = createPiniaAuthStore(defineStore, 'auth')

import { auth, useAuthStore } from '@/utils/auth'

const store = useAuthStore()
await store.canUserAccess(true)

if (!store.isAuth) {
  auth.redirectToLogin() // remote → loginUrl; local → your login route
}

6. Why auth.client?

PHP already owns mode, key, JWT secret, and login URLs. The SPA must not invent them.

auth.client publishes a safe subset to window.__PINOOX__.auth (via pinoox_bootstrap()).

| Stays on server | May go to the client | | --------------- | -------------------- | | jwt_secret, lifetimes, … | mode, key, provider, source | | | optional: strategy, loginUrl, baseUrl, endpoints |

app.php auth.client  →  pinker + pinoox_bootstrap()  →  __PINOOX__.auth
                                                          ↓
                                              createAuth() / createHttp()

Twig (order matters):

{{ pinoox_bootstrap(bootstrap|default({}))|raw }}
{{ vite_tags() }}

auth.client — what gets into __PINOOX__.auth

The server always resolves a base payload from auth + transport:

// Always available on the server (AuthConfig::forClient base)
[
    'mode'     => 'jwt',                 // jwt | cookie | session
    'key'      => 'pinoox_ecosystem',    // localStorage / cookie name
    'provider' => 'com_pinoox_account',  // package that owns auth (or this app)
    'source'   => 'com_pinoox_account',  // transport auth source (or null)
]

auth.client decides how much of that (and extras) the browser may see.

1) true — publish the full base (default)

// e.g. com_pinoox_shop — independent login
'auth' => [
    'mode' => 'jwt',
    'key' => 'pinoox_shop_auth',
    'client' => true,
],

// window.__PINOOX__.auth
{ mode: 'jwt', key: 'pinoox_shop_auth', provider: 'com_pinoox_shop', source: null }

Use for a normal local login app. createAuth() gets mode + key with no JS hardcoding.

2) false — publish nothing

'auth' => [
    'mode' => 'jwt',
    'key' => 'pinoox_crm_auth',
    'client' => false,
],

__PINOOX__.auth is omitted. You must pass everything in JS:

createAuth({ mode: 'jwt', key: 'pinoox_crm_auth', strategy: 'local' })

Use only when you deliberately keep auth config off the page (or hydrate from elsewhere).

3) List — whitelist of base fields only

A PHP list (array_is_list) means: from the base payload, keep only these keys. Nothing else is added.

// Account (or Shop) — only mode + key in the page; hide provider/source package names
'auth' => [
    'mode' => 'jwt',
    'key' => 'pinoox_ecosystem',
    'client' => ['mode', 'key'],
],

// window.__PINOOX__.auth
{ mode: 'jwt', key: 'pinoox_ecosystem' }
// no provider, no source

When to use

• The SPA only needs mode + key to store/send the token
• You do not want provider / source package ids visible in page HTML
• Strategy / login URLs are either defaults (local) or set in JS / via a map (form 4)

Allowed whitelist names (only these exist on the base):

| Field | Purpose | | ----- | ------- | | mode | How the token is stored / sent | | key | Storage key (localStorage name) | | provider | Auth-owning package | | source | Transport auth source package |

Unknown names are ignored. You cannot whitelist strategy / loginUrl here — those are not base fields; use a map (below).

Another example — token key only (mode defaults to jwt in createAuth if missing, but publishing mode is safer):

'client' => ['key'],
// → __PINOOX__.auth = { key: 'pinoox_ecosystem' }

4) Map — base + extras (remote apps)

An associative array merges onto the full base. Use this for strategy, loginUrl, baseUrl, endpoints:

// com_pinoox_shop — depends on Account
'auth' => [
    'client' => [
        'strategy' => 'remote',
        'loginUrl' => '/account/login',
        'baseUrl' => '/account/api/v1',
        'endpoints' => [
            'me' => 'auth/get',
            'logout' => 'auth/logout',
        ],
    ],
],

// window.__PINOOX__.auth
{
  mode: 'jwt',
  key: 'pinoox_ecosystem',   // inherited via transport from Account
  provider: '…',
  source: '…',
  strategy: 'remote',
  loginUrl: '/account/login',
  baseUrl: '/account/api/v1',
  endpoints: { me: 'auth/get', logout: 'auth/logout' },
}

List vs map (easy rule)

| Shape | PHP | Meaning | | ----- | --- | ------- | | List | ['mode', 'key'] | Filter base → only these keys | | Map | ['strategy' => 'remote', …] | Keep all base keys, then merge extras |

// ❌ Wrong — this is a list, so "strategy" is ignored (not a base field)
'client' => ['mode', 'key', 'strategy'],

// ✅ Right — map merges strategy onto the full base
'client' => [
    'strategy' => 'remote',
    'loginUrl' => '/account/login',
],

Aliases for auth.client: via, expose, bootstrap.

7. App configuration reference

Strategies

| Value | Meaning | | ----- | ------- | | local (default) | This app owns login | | remote | Redirect to another app’s login |

Aliases: provider → local, consumer / external → remote.

baseUrl + endpoints

Prefer a shared API prefix (here: Account as provider):

'baseUrl' => '/account/api/v1',
'endpoints' => [
    'me' => 'auth/get',       // → /account/api/v1/auth/get
    'logout' => 'auth/logout',
],

Or absolute paths (no baseUrl):

'endpoints' => [
    'me' => '/account/api/v1/auth/get',
    'logout' => '/account/api/v1/auth/logout',
],

For a dependent that validates the session on its own API (same shared key):

// com_pinoox_crm with transport.user => platform or account
'baseUrl' => '/crm/api/v1',
'endpoints' => [
    'me' => 'auth/get',
    'logout' => 'auth/logout',
],

Rules:

• https://… or path starting with / → used as-is
• relative + baseUrl → joined
• relative without baseUrl → left as-is

Modes

| mode | Storage | Request | | ---- | ------- | ------- | | jwt | token under auth.key | Authorization: Bearer … | | cookie / session | optional | cookies (credentials: include) |

8. Theme integration

Login page (local / provider only)

<script setup>
import { http, useAuthStore } from '@/utils/auth'
import { useAuthRedirect } from '@pinooxhq/auth/vue'

const store = useAuthStore()
const { redirectBack } = useAuthRedirect()

const onLogin = async () => {
  const { data } = await http.post('auth/login', { username, password })
  const body = data?.data ?? data
  store.login(body.token, body.user)
  redirectBack()
}
</script>

Router guard (any app)

import { auth, useAuthStore } from '@/utils/auth'

export async function authGuard(to, _from, next) {
  const store = useAuthStore()
  store.syncTokenFromStorage()

  if (!store.isAuth) {
    await store.canUserAccess(true)
  }

  if (to.meta.requiresAuth && !store.isAuth) {
    auth.redirectToLogin()
    return
  }

  next()
}

On remote apps (Shop / CRM), auth.redirectToLogin() goes to loginUrl?redirect=<current path>.

9. HTTP, redirects, adapters

HTTP

createHttp({ auth, axios }) wires:

• Authorization from auth.getAuthHeader()
• 401 → auth.notifyUnauthorized()
• shared transport for login / me / logout

baseURL defaults to __PINOOX__.url.API.

Redirects

auth.redirectToLogin() // remote → other app; local → loginUrl / endpoints.login
auth.redirectBack()    // after login → safe ?redirect= (SITE origin aware for Vite HMR)

import { useAuthRedirect } from '@pinooxhq/auth/vue'
const { redirectQuery, redirectBack, returnUrl } = useAuthRedirect()

Vue / React / Svelte

import { useAuth, useAuthRedirect, createPiniaAuthStore } from '@pinooxhq/auth/vue'
import { AuthProvider, useAuth } from '@pinooxhq/auth/react'
import { createAuthStore, createAuthRedirect } from '@pinooxhq/auth/svelte'

10. API reference

auth.login({ username, password })  // local only; remote → redirect
auth.me()
auth.logout()
auth.getToken() / auth.setToken(t) / auth.clearToken()
auth.getAuthHeader()
auth.redirectToLogin() / auth.redirectBack()
auth.getReturnUrl() / auth.getRedirectQuery()
auth.notifyUnauthorized()

http.get / http.post / …

11. Vite

@pinooxhq/vite-plugin — Twig shell + Vite entry so __PINOOX__ (and auth.client) loads before the SPA.

{{ pinoox_bootstrap(bootstrap|default({}))|raw }}
{{ vite_tags() }}

License

MIT