Added Workspace Docs
This commit is contained in:
parent
07aad6c69e
commit
61f15e1325
|
|
@ -0,0 +1,5 @@
|
|||
var NAV_DATA = {
|
||||
title: 'Workspace',
|
||||
path: 'index.html',
|
||||
children: []
|
||||
};
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
.wsnav
|
||||
{
|
||||
position: fixed;
|
||||
top: 0;
|
||||
left: 0;
|
||||
right: 0;
|
||||
z-index: 100;
|
||||
background: #1a1d27;
|
||||
border-bottom: 1px solid #2a2d3a;
|
||||
font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
|
||||
font-size: 0.82rem;
|
||||
}
|
||||
|
||||
.wsnav-inner
|
||||
{
|
||||
width: 65em;
|
||||
margin: 0 auto;
|
||||
padding: 0.45rem 1.5rem;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.25rem;
|
||||
}
|
||||
|
||||
.wsnav a
|
||||
{
|
||||
color: #7c8cff;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.wsnav a:hover
|
||||
{
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
/* ── Breadcrumb ── */
|
||||
|
||||
.wsnav-crumb
|
||||
{
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.35rem;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.wsnav-sep
|
||||
{
|
||||
color: #4a4e6a;
|
||||
font-size: 0.9em;
|
||||
}
|
||||
|
||||
.wsnav-current
|
||||
{
|
||||
color: #e2e4ed;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
/* ── Siblings ── */
|
||||
|
||||
.wsnav-siblings
|
||||
{
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.45rem;
|
||||
flex-wrap: wrap;
|
||||
color: #7b7f96;
|
||||
font-size: 0.88em;
|
||||
}
|
||||
|
||||
.wsnav-sib-current
|
||||
{
|
||||
color: #e2e4ed;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.wsnav-sib-sep
|
||||
{
|
||||
color: #4a4e6a;
|
||||
}
|
||||
|
||||
/* ── Children ── */
|
||||
|
||||
.wsnav-children
|
||||
{
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.75rem;
|
||||
flex-wrap: wrap;
|
||||
font-size: 0.88em;
|
||||
padding-top: 0.1rem;
|
||||
border-top: 1px solid #2a2d3a;
|
||||
margin-top: 0.1rem;
|
||||
}
|
||||
|
|
@ -0,0 +1,133 @@
|
|||
(function ()
|
||||
{
|
||||
function getCurrentPath()
|
||||
{
|
||||
var href = window.location.href.replace(/\\/g, '/');
|
||||
var marker = 'workspace/';
|
||||
var idx = href.lastIndexOf(marker);
|
||||
if (idx === -1) return 'index.html';
|
||||
var after = href.slice(idx + marker.length);
|
||||
return after || 'index.html';
|
||||
}
|
||||
|
||||
function findNode(node, targetPath, ancestors)
|
||||
{
|
||||
if (node.path === targetPath) return { node: node, ancestors: ancestors };
|
||||
var children = node.children || [];
|
||||
for (var i = 0; i < children.length; i++)
|
||||
{
|
||||
var result = findNode(children[i], targetPath, ancestors.concat(node));
|
||||
if (result) return result;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function makeLink(node, label)
|
||||
{
|
||||
var a = document.createElement('a');
|
||||
a.href = NAV_ROOT + node.path;
|
||||
a.textContent = label || node.title;
|
||||
return a;
|
||||
}
|
||||
|
||||
function render()
|
||||
{
|
||||
var currentPath = getCurrentPath();
|
||||
var found = findNode(NAV_DATA, currentPath, []);
|
||||
|
||||
var nav = document.createElement('nav');
|
||||
nav.className = 'wsnav';
|
||||
|
||||
var inner = document.createElement('div');
|
||||
inner.className = 'wsnav-inner';
|
||||
nav.appendChild(inner);
|
||||
|
||||
// ── Breadcrumb ───────────────────────────────────────────────────
|
||||
var crumb = document.createElement('div');
|
||||
crumb.className = 'wsnav-crumb';
|
||||
|
||||
var ancestors = found ? found.ancestors : [];
|
||||
var currentNode = found ? found.node : null;
|
||||
|
||||
for (var i = 0; i < ancestors.length; i++)
|
||||
{
|
||||
var a = makeLink(ancestors[i]);
|
||||
crumb.appendChild(a);
|
||||
var sep = document.createElement('span');
|
||||
sep.className = 'wsnav-sep';
|
||||
sep.textContent = '›';
|
||||
crumb.appendChild(sep);
|
||||
}
|
||||
|
||||
var current = document.createElement('span');
|
||||
current.className = 'wsnav-current';
|
||||
current.textContent = currentNode ? currentNode.title : currentPath;
|
||||
crumb.appendChild(current);
|
||||
|
||||
inner.appendChild(crumb);
|
||||
|
||||
// ── Siblings ─────────────────────────────────────────────────────
|
||||
var parent = ancestors.length > 0 ? ancestors[ancestors.length - 1] : null;
|
||||
var siblings = parent ? (parent.children || []) : [];
|
||||
|
||||
if (siblings.length > 1)
|
||||
{
|
||||
var sibRow = document.createElement('div');
|
||||
sibRow.className = 'wsnav-siblings';
|
||||
|
||||
for (var j = 0; j < siblings.length; j++)
|
||||
{
|
||||
var sib = siblings[j];
|
||||
if (sib.path === currentPath)
|
||||
{
|
||||
var mark = document.createElement('span');
|
||||
mark.className = 'wsnav-sib-current';
|
||||
mark.textContent = sib.title;
|
||||
sibRow.appendChild(mark);
|
||||
}
|
||||
else
|
||||
{
|
||||
sibRow.appendChild(makeLink(sib));
|
||||
}
|
||||
|
||||
if (j < siblings.length - 1)
|
||||
{
|
||||
var div = document.createElement('span');
|
||||
div.className = 'wsnav-sib-sep';
|
||||
div.textContent = '·';
|
||||
sibRow.appendChild(div);
|
||||
}
|
||||
}
|
||||
|
||||
inner.appendChild(sibRow);
|
||||
}
|
||||
|
||||
// ── Children ─────────────────────────────────────────────────────
|
||||
var children = currentNode ? (currentNode.children || []) : [];
|
||||
|
||||
if (children.length > 0)
|
||||
{
|
||||
var childRow = document.createElement('div');
|
||||
childRow.className = 'wsnav-children';
|
||||
|
||||
for (var k = 0; k < children.length; k++)
|
||||
{
|
||||
childRow.appendChild(makeLink(children[k]));
|
||||
}
|
||||
|
||||
inner.appendChild(childRow);
|
||||
}
|
||||
|
||||
document.body.insertBefore(nav, document.body.firstChild);
|
||||
document.body.style.paddingTop = (nav.offsetHeight + 8) + 'px';
|
||||
}
|
||||
|
||||
if (document.readyState === 'loading')
|
||||
{
|
||||
document.addEventListener('DOMContentLoaded', render);
|
||||
}
|
||||
else
|
||||
{
|
||||
render();
|
||||
}
|
||||
})();
|
||||
|
|
@ -0,0 +1,200 @@
|
|||
*, *::before, *::after
|
||||
{
|
||||
box-sizing: border-box;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
:root
|
||||
{
|
||||
--bg: #0f1117;
|
||||
--surface: #1a1d27;
|
||||
--border: #2a2d3a;
|
||||
--text: #e2e4ed;
|
||||
--muted: #7b7f96;
|
||||
--accent: #7c8cff;
|
||||
--tag-bg: #1e2235;
|
||||
--tag-text: #9ba4c7;
|
||||
--font-size: 20px;
|
||||
}
|
||||
|
||||
html
|
||||
{
|
||||
font-size: calc( var( --font-size ) );
|
||||
-webkit-font-smoothing: antialiased;
|
||||
}
|
||||
|
||||
body
|
||||
{
|
||||
background: var(--bg);
|
||||
color: var(--text);
|
||||
font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
|
||||
line-height: 1.7;
|
||||
padding: calc( var( --font-size ) * 3 ) calc( var( --font-size ) * 1.5 ) calc( var( --font-size ) * 6 );
|
||||
}
|
||||
|
||||
.page
|
||||
{
|
||||
max-width: 50em;
|
||||
margin: 0 auto;
|
||||
}
|
||||
|
||||
header
|
||||
{
|
||||
margin-bottom: calc( var( --font-size ) * 3 );
|
||||
padding-bottom: calc( var( --font-size ) * 1.5 );
|
||||
border-bottom: 1px solid var(--border);
|
||||
}
|
||||
|
||||
header .date
|
||||
{
|
||||
font-size: calc( var( --font-size ) * 0.8 );
|
||||
letter-spacing: 0.1em;
|
||||
text-transform: uppercase;
|
||||
color: var(--muted);
|
||||
margin-bottom: calc( var( --font-size ) * 0.75 );
|
||||
}
|
||||
|
||||
header h1
|
||||
{
|
||||
font-size: calc( var( --font-size ) * 1.9 );
|
||||
font-weight: 700;
|
||||
letter-spacing: -0.02em;
|
||||
color: var(--text);
|
||||
}
|
||||
|
||||
header .subtitle
|
||||
{
|
||||
margin-top: calc( var( --font-size ) * 0.5 );
|
||||
color: var(--muted);
|
||||
font-size: calc( var( --font-size ) * 0.95 );
|
||||
}
|
||||
|
||||
section
|
||||
{
|
||||
margin-bottom: calc( var( --font-size ) * 2.5 );
|
||||
}
|
||||
|
||||
section h2
|
||||
{
|
||||
font-size: calc( var( --font-size ) * 1.25 );
|
||||
font-weight: 600;
|
||||
letter-spacing: 0.12em;
|
||||
text-transform: uppercase;
|
||||
color: var(--accent);
|
||||
margin-bottom: calc( var( --font-size ) * 1 );
|
||||
}
|
||||
|
||||
.card
|
||||
{
|
||||
background: var(--surface);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 8px;
|
||||
padding: calc( var( --font-size ) * 1.25 ) calc( var( --font-size ) * 1.5 );
|
||||
margin-bottom: calc( var( --font-size ) * 0.75 );
|
||||
}
|
||||
|
||||
.card h3
|
||||
{
|
||||
font-size: calc( var( --font-size ) * 1 );
|
||||
font-weight: 600;
|
||||
margin-bottom: calc( var( --font-size ) * 0.35 );
|
||||
color: var(--text);
|
||||
}
|
||||
|
||||
.card p
|
||||
{
|
||||
font-size: calc( var( --font-size ) * 0.9 );
|
||||
color: var(--muted);
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.tags
|
||||
{
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: calc( var( --font-size ) * 0.4 );
|
||||
margin-top: calc( var( --font-size ) * 0.75 );
|
||||
}
|
||||
|
||||
.tag
|
||||
{
|
||||
background: var(--tag-bg);
|
||||
color: var(--tag-text);
|
||||
font-size: calc( var( --font-size ) * 0.75 );
|
||||
padding: calc( var( --font-size ) * 0.2 ) calc( var( --font-size ) * 0.6 );
|
||||
border-radius: 4px;
|
||||
font-family: ui-monospace, "Cascadia Code", monospace;
|
||||
}
|
||||
|
||||
.decision
|
||||
{
|
||||
border-left: 3px solid var(--accent);
|
||||
padding-left: calc( var( --font-size ) * 1 );
|
||||
margin-bottom: calc( var( --font-size ) * 2 );
|
||||
}
|
||||
|
||||
.decision p
|
||||
{
|
||||
font-size: calc( var( --font-size ) * 0.9 );
|
||||
color: var(--muted);
|
||||
}
|
||||
|
||||
.decision strong
|
||||
{
|
||||
color: var(--text);
|
||||
display: block;
|
||||
margin-bottom: calc( var( --font-size ) * 0.2 );
|
||||
}
|
||||
|
||||
footer
|
||||
{
|
||||
margin-top: calc( var( --font-size ) * 4 );
|
||||
padding-top: calc( var( --font-size ) * 1.5 );
|
||||
border-top: 1px solid var(--border);
|
||||
font-size: calc( var( --font-size ) * 0.8 );
|
||||
color: var(--muted);
|
||||
}
|
||||
|
||||
a
|
||||
{
|
||||
color: var(--accent);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
a:hover
|
||||
{
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
code
|
||||
{
|
||||
font-family: ui-monospace, "Cascadia Code", "Fira Code", monospace;
|
||||
font-size: 0.85em;
|
||||
color: var(--accent);
|
||||
background: var(--tag-bg);
|
||||
padding: 0.1em 0.35em;
|
||||
border-radius: 3px;
|
||||
}
|
||||
|
||||
pre
|
||||
{
|
||||
background: #0a0c14;
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 6px;
|
||||
padding: calc( var( --font-size ) * 1 ) calc( var( --font-size ) * 1.25 );
|
||||
overflow-x: auto;
|
||||
font-family: ui-monospace, "Cascadia Code", "Fira Code", monospace;
|
||||
font-size: calc( var( --font-size ) * 0.82 );
|
||||
line-height: 1.6;
|
||||
color: var(--text);
|
||||
margin-top: calc( var( --font-size ) * 0.75 );
|
||||
}
|
||||
|
||||
pre code
|
||||
{
|
||||
background: none;
|
||||
color: inherit;
|
||||
padding: 0;
|
||||
font-size: inherit;
|
||||
}
|
||||
|
|
@ -0,0 +1,329 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>rokojori-auth — Developer Documentation</title>
|
||||
<link rel="stylesheet" href="_assets_/styles.css">
|
||||
<link rel="stylesheet" href="_assets_/nav.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="page">
|
||||
|
||||
<header>
|
||||
<p class="date">Project Documentation</p>
|
||||
<h1>rokojori-auth</h1>
|
||||
<p class="subtitle">
|
||||
Centralized auth service for all rokojori projects, deployed at
|
||||
<code>account.rokojori.com</code>. Developer reference for human and agent contributors.
|
||||
</p>
|
||||
</header>
|
||||
|
||||
<section>
|
||||
<h2>What it is</h2>
|
||||
|
||||
<div class="card">
|
||||
<p>
|
||||
rokojori-auth is a standalone Express service that owns all identity for the
|
||||
rokojori ecosystem — registration, login, JWT issuance, password reset, roles,
|
||||
products, and global user settings. Every other rokojori project (Roject, future
|
||||
apps, desktop tools) plugs in by verifying the shared JWT. No auth code to write,
|
||||
no user table to maintain in the client app.
|
||||
</p>
|
||||
<p style="margin-top:0.75rem">
|
||||
The service issues a short-lived access token (1 hour) and a long-lived refresh
|
||||
token (30 days). For browser clients both are set as <code>HttpOnly</code> cookies
|
||||
on <code>.rokojori.com</code>, making them automatically available to all subdomains.
|
||||
Non-browser clients (Electron, CLI, Godot) receive the tokens in the response body
|
||||
and manage them locally.
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>Features</h2>
|
||||
|
||||
<div class="card">
|
||||
<h3>Authentication</h3>
|
||||
<p>
|
||||
Email and password registration and login. Passwords are hashed with bcrypt (cost 10).
|
||||
On login or register, the server issues an access token cookie and a refresh token
|
||||
cookie, both scoped to <code>.rokojori.com</code>. The refresh token is also returned
|
||||
in the response body for non-browser clients.
|
||||
</p>
|
||||
<div class="tags">
|
||||
<span class="tag">POST /api/auth/register</span>
|
||||
<span class="tag">POST /api/auth/login</span>
|
||||
<span class="tag">POST /api/auth/logout</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>Token refresh</h3>
|
||||
<p>
|
||||
Browser clients whose access token has expired are redirected to
|
||||
<code>GET /api/auth/refresh-session?redirect=...</code>. The server reads the
|
||||
refresh token cookie, rotates both tokens, and redirects back. Non-browser clients
|
||||
call <code>POST /api/auth/refresh</code> with the refresh token in the request body.
|
||||
</p>
|
||||
<div class="tags">
|
||||
<span class="tag">GET /api/auth/refresh-session</span>
|
||||
<span class="tag">POST /api/auth/refresh</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>Password reset</h3>
|
||||
<p>
|
||||
Forgot-password sends a time-limited email link (1 hour). The endpoint is
|
||||
rate-limited per IP with an escalating response delay (5 s → 15 s → 30 s,
|
||||
hard block after 20 attempts in 20 minutes) to prevent email spam.
|
||||
The response is always <code>{ ok: true }</code> regardless of whether the
|
||||
email exists, to avoid leaking account information.
|
||||
</p>
|
||||
<div class="tags">
|
||||
<span class="tag">POST /api/auth/forgot-password</span>
|
||||
<span class="tag">POST /api/auth/reset-password</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>Profile and account management</h3>
|
||||
<p>
|
||||
Authenticated users can read their profile, update global settings, change their
|
||||
password (requires current password), and permanently delete their account.
|
||||
Deletion removes the user record and all associated tokens.
|
||||
</p>
|
||||
<div class="tags">
|
||||
<span class="tag">GET /api/auth/me</span>
|
||||
<span class="tag">PATCH /api/auth/me/settings</span>
|
||||
<span class="tag">POST /api/auth/me/password</span>
|
||||
<span class="tag">DELETE /api/auth/me</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>Roles</h3>
|
||||
<p>
|
||||
Three built-in roles: <code>user</code> (default on registration),
|
||||
<code>admin</code> (enhanced profile, user list), and <code>superadmin</code>
|
||||
(can manage roles of other users). Roles are included in the JWT payload so
|
||||
client apps can gate features without a round-trip. App-specific roles (e.g.
|
||||
editor of a specific Roject project) stay in the respective app, keyed by
|
||||
<code>userId</code>.
|
||||
</p>
|
||||
<p style="margin-top:0.75rem">
|
||||
Bootstrap: set <code>INITIAL_SUPERADMIN_EMAIL</code> in <code>.env</code>.
|
||||
The first registration with that email is automatically promoted to
|
||||
<code>superadmin</code>, provided no superadmin exists yet.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>Products</h3>
|
||||
<p>
|
||||
Each user record has a <code>products</code> array. When a purchase is confirmed
|
||||
(planned: via a Polar webhook), a product entry is appended. Apps read the product
|
||||
list from the JWT at runtime — no Polar dependency needed outside the webhook handler.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>Rate limiting</h3>
|
||||
<p>
|
||||
In-memory per-IP rate limits on all sensitive endpoints. Windows and thresholds:
|
||||
</p>
|
||||
<ul style="margin-top:0.75rem;line-height:1.9;font-size:0.9rem;color:var(--muted)">
|
||||
<li><strong style="color:var(--text)">Login</strong> — 10 attempts / 15 min; delay of 3 s added after attempt 5</li>
|
||||
<li><strong style="color:var(--text)">Register</strong> — 5 attempts / hour, hard block</li>
|
||||
<li><strong style="color:var(--text)">Forgot-password</strong> — 20 attempts / 20 min; escalating delay 5 s → 15 s → 30 s</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>HTML pages</h3>
|
||||
<p>
|
||||
Five self-contained pages served at <code>account.rokojori.com</code>,
|
||||
shared across all rokojori apps. All pages are plain HTML with inline
|
||||
CSS and JavaScript — no framework, no build step.
|
||||
</p>
|
||||
<ul style="margin-top:0.75rem;line-height:1.9;font-size:0.9rem;color:var(--muted)">
|
||||
<li><code>login.html</code> — accepts <code>?redirect=</code> query param</li>
|
||||
<li><code>register.html</code> — accepts <code>?redirect=</code> query param</li>
|
||||
<li><code>profile.html</code> — change password, delete account; admin/superadmin see user list</li>
|
||||
<li><code>forgot-password.html</code></li>
|
||||
<li><code>reset-password.html</code> — reads <code>?token=</code> from URL; includes hidden email field for browser password-manager integration</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>Technical Implementation</h2>
|
||||
|
||||
<div class="card">
|
||||
<h3>Stack</h3>
|
||||
<p>
|
||||
Node.js + Express, TypeScript compiled on the fly with <code>ts-node</code>.
|
||||
No database — all data lives as JSON files in <code>build/data/</code>
|
||||
(auto-created on first run). All entity IDs are UUIDs via
|
||||
<code>crypto.randomUUID()</code>. Email via Nodemailer (<code>SMTPEmailSender</code>),
|
||||
configured entirely through environment variables.
|
||||
</p>
|
||||
<div class="tags">
|
||||
<span class="tag">Node.js</span>
|
||||
<span class="tag">Express</span>
|
||||
<span class="tag">ts-node</span>
|
||||
<span class="tag">jsonwebtoken</span>
|
||||
<span class="tag">bcryptjs</span>
|
||||
<span class="tag">nodemailer</span>
|
||||
<span class="tag">cookie-parser</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>File structure</h3>
|
||||
<pre><code>rokojori-auth/
|
||||
source/
|
||||
server/
|
||||
routes/
|
||||
auth.ts — all auth + profile endpoints
|
||||
admin.ts — user list + role management (admin/superadmin)
|
||||
middleware/
|
||||
requireAuth.ts — JWT verification (cookie or Authorization header)
|
||||
requireAdmin.ts — role guards (requireAdmin, requireSuperAdmin)
|
||||
email/
|
||||
EmailSender.ts — interface
|
||||
SMTPEmailSender.ts
|
||||
EmailService.ts — static facade
|
||||
db.ts — users, refreshTokens, resetTokens (JSON file storage)
|
||||
roles.ts — role → permissions map, helper functions
|
||||
rateLimiter.ts — per-IP in-memory rate limiters
|
||||
index.ts — Express entry point
|
||||
pages/ — HTML pages (copied to build/app/ by build script)
|
||||
scripts/
|
||||
copy-pages.js
|
||||
workspace/ — this documentation</code></pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>Data model</h3>
|
||||
<pre><code>// users.json
|
||||
{
|
||||
"id": "uuid",
|
||||
"email": "user@example.com",
|
||||
"passwordHash": "...",
|
||||
"roles": ["user"],
|
||||
"products": [
|
||||
{ "id": "roject-pro", "acquiredAt": "2026-07-13", "source": "polar" }
|
||||
],
|
||||
"settings": { "theme": "dark", "language": "en" },
|
||||
"createdAt": "2026-07-13T00:00:00Z"
|
||||
}
|
||||
|
||||
// refreshTokens.json
|
||||
{ "token": "uuid", "userId": "uuid", "expiresAt": "..." }
|
||||
|
||||
// resetTokens.json
|
||||
{ "token": "uuid", "userId": "uuid", "expiresAt": "..." }</code></pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>JWT payload</h3>
|
||||
<p>
|
||||
Access tokens are signed HS256 with <code>JWT_SECRET</code> (shared across all
|
||||
services). They carry everything a client app needs to know — no round-trip to
|
||||
rokojori-auth required at runtime.
|
||||
</p>
|
||||
<pre><code>{
|
||||
"userId": "uuid",
|
||||
"email": "user@example.com",
|
||||
"roles": ["user"],
|
||||
"products": ["roject-pro"],
|
||||
"settings": { "theme": "dark" }
|
||||
}</code></pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>Deployment</h3>
|
||||
<p>
|
||||
Running on Server A at <code>account.rokojori.com</code>. nginx handles TLS
|
||||
termination (Let's Encrypt) and reverse-proxies to the Node.js process on port
|
||||
3001, managed by a systemd service (<code>rokojori-auth.service</code>).
|
||||
<code>trust proxy</code> is enabled so the rate limiter sees real client IPs.
|
||||
</p>
|
||||
<div class="tags">
|
||||
<span class="tag">account.rokojori.com</span>
|
||||
<span class="tag">nginx + Let's Encrypt</span>
|
||||
<span class="tag">systemd</span>
|
||||
<span class="tag">port 3001</span>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>Planned</h2>
|
||||
|
||||
<div class="card">
|
||||
<h3>Polar payment webhook</h3>
|
||||
<p>
|
||||
When a user purchases a product through Polar (merchant of record — handles
|
||||
VAT/tax automatically), Polar fires a webhook to rokojori-auth. The handler
|
||||
verifies the Polar signature, finds the user by email, and appends a product
|
||||
entry to their record. The updated product list is included in the next JWT
|
||||
issued for that user. No Polar dependency is needed in any other service.
|
||||
</p>
|
||||
<div class="tags">
|
||||
<span class="tag">POST /api/webhooks/polar</span>
|
||||
<span class="tag">signature verification</span>
|
||||
<span class="tag">products array</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h3>Security hardening pass</h3>
|
||||
<p>
|
||||
A dedicated review pass covering: helmet.js headers, CSRF considerations for the
|
||||
cookie flow, refresh token rotation audit, token expiry edge cases, and a review
|
||||
of the rate limiter behaviour under proxy chains.
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>Related — Roject</h2>
|
||||
|
||||
<div class="card">
|
||||
<p>
|
||||
<strong style="color:var(--text)">Roject</strong> is the first client app of
|
||||
rokojori-auth. It is a self-hosted, agent-based IDE deployed at
|
||||
<code>roject.rokojori.com</code>. After the auth integration is complete, Roject
|
||||
will drop its own user system entirely and become a JWT-validating client: it
|
||||
redirects to <code>account.rokojori.com/login</code> for login, reads the shared
|
||||
cookie, and verifies the JWT locally on every request.
|
||||
</p>
|
||||
<p style="margin-top:0.75rem">
|
||||
For deeper context on the overall ecosystem, coding conventions, and how to work
|
||||
with the codebase, consult the <strong style="color:var(--text)">Roject workspace
|
||||
documentation</strong>. It contains guides (writing TypeScript code, backend routes,
|
||||
editor panels), repeatable actions (update history, update outline), and reference
|
||||
docs (Editor Singleton, client/server split). Ask for the Roject workspace docs
|
||||
for those details.
|
||||
</p>
|
||||
<div class="tags">
|
||||
<span class="tag">roject.rokojori.com</span>
|
||||
<span class="tag">JWT client</span>
|
||||
<span class="tag">shared .rokojori.com cookie</span>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<footer>
|
||||
rokojori-auth — developer documentation
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
<script>var NAV_ROOT = './';</script>
|
||||
<script src="_assets_/nav-data.js"></script>
|
||||
<script src="_assets_/nav.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Reference in New Issue