Version 1 of 1 · · razie · in person · Current version

name
d3-f-accounts
description
Accounts, members and projects — one account per person, handles, log-in and SSO, member roles and view/edit access, joining and invites, notices, making a project, plans and quotas. Get skills only from /api/v2/skills/d3.
feature
acc
concepts
[account, member, joinRequest, invite, notice, session, project, plan]
tags
#skill #feature #d3skill #wip

d3-f-accounts

Intro

People, projects, members, plans and quotas.

One account per person for the whole site; each project is a subdomain with its own members, topics and data, isolated from every other. This covers who a person is, what their role lets them read and write, how they join, log in and move between projects, how projects are made, and the plans and quotas that bound them. What an AI may do on its own is d3-f-permissions; tokens are d3-f-tokens; agreeing to terms is d3-f-consent. Spec: Spec › joining, Spec › roles, Spec › quotas.

Essentials

  • R-acct-1 Name people by their handle (bob), never their email (only admins see emails, on the members page).
  • R-acct-2 Your token never exceeds your person's role in the project.
  • R-acct-3 Pages never ask for a token; tokens travel only in API calls.
  • R-acct-4 NEVER change a person's plan; only the person does (the Architect may set anyone's).
  • R-acct-5 At a quota, tell your person; NEVER work around it.
  • R-acct-6 NEVER send a broadcast; you may draft one (preview link first).
  • R-acct-7 NEVER re-create a demo's data by hand; the person uses Reset all.

Concepts

account

One person, site-wide. Also called: user, person, profile. Fields: handle (made at sign-up from the email's first part, a number added when taken; the person changes it in Preferences, a taken or malformed one refused), name, email, plan, consents, thoughtsHidden, flow.

account_me

  • Summary: who you are here and where your person is a member.
  • When: at start; before naming a role or project.
  • Needs: —
  • Call: GET /api/v2/me → {handle, name, here: {project, role, level}, projects: [{name, level, lastUsed}], aiConnected} (a visitor: {visitor: true}).
  • Rules: R-acct-1.
  • Errors: E_AUTH (401).
  • Gotchas: —

member

A person's role in one project. Roles nest: public < member < mod < admin; the Architect (stored as god) is above admin on every project. admin: members, roles, permissions; mod: settings, special pages, specs; member: what access allows. Fields: role. Access is view and edit (each a level), most specific first: the topic's own frontmatter, then the project's categories: in Settings:PROJECT, then the category's annotation (Settings stays mod), then the project's view/edit setting. Settings: join in Settings:PROJECT (admin-only): request (default — Request to join; an admin approves or invites), open (Join makes a member), invite (only by an admin's invite). Reading is separate: view (a private project is view: member).

member_join

  • Summary: join per the project's join setting.
  • When: your person wants into a project.
  • Needs: the project's join.
  • Call: Request to join (request) or Join (open) on the project; invite → only by invite.
  • Rules: Everyone joins as member; the creator owns the project as its first admin.
  • Errors: 403 not a member → the page says how to join.
  • Gotchas: —

member_role

  • Summary: admins change roles on the members page; only admins give mod or admin.
  • When: a person's role must change.
  • Needs: an admin.
  • Call: /d2admin/members (Admin card Members): every member with their role.
  • Rules: —
  • Errors: E_FORBIDDEN (403) with need: → raise the role, or a mod changes the topic's access.
  • Gotchas: —

joinRequest

A person asking to join a project whose join is request; an admin approves (they become a member) or declines. Fields: the person, when. Also called: a join request, asking to join. Notices N_JOIN (to the admins), N_APPROVED / N_DECLINED (to the person).

invite

An admin's invitation to one address, whatever join says. Fields: the address, a link good 7 days, its Copy link on the members page.

invite_send

  • Summary: an admin invites an address; a one-address link, 7 days.
  • When: adding someone.
  • Needs: an admin; the address.
  • Call: the members page.
  • Rules: Opened after logging in or signing up as that address; an existing account also gets a notice. Only the invited address can decline.
  • Errors: —
  • Gotchas: —

notice

A message to a person, shown on every project (a red bar on homes and a count in the user menu while anything waits), one line per code with a count. Codes: N_JOIN, N_APPROVED, N_INVITE, N_ACCEPTED, N_DECLINED, N_ROLE, N_QUOTA_FULL…; pipeline items send none.

notice_clear

  • Summary: clearing a line clears all of its count.
  • When: the person has seen them.
  • Needs: —
  • Call: the notices line in the user menu.
  • Rules: —
  • Errors: —
  • Gotchas: —

notice_broadcast

  • Summary: only the Architect sends to every account; you may draft.
  • When: your person wants a site-wide notice.
  • Needs: the text; a preview link first.
  • Call: a draft for the Architect.
  • Rules: R-acct-6.
  • Errors: —
  • Gotchas: —

session

A person's log-in on one project. Sign up and log in on the base (aiputty.com), the SSO hub. A session from one project doesn't log in on another.

session_login

  • Summary: log in on the hub; other projects need no password.
  • When: a person must log in, or moves between projects.
  • Needs: —
  • Call: Log in (comes back to the same page). On another project where they're a member: a one-time code (one project, one minute, redeemed on the server); not a member → that project's own form.
  • Rules: Logging in anywhere logs the hub in; logging out of a project logs the hub out. Lands on d2welcome with no project of their own, else the project used last. My projects is in the user menu.
  • Errors: E_LOCKED → too many wrong passwords: wait, or an admin unlocks · E_ORIGIN → a form post from another origin.
  • Gotchas: —

session_denied

  • Summary: a forbidden page answers in place, never a redirect.
  • When: a page someone may not see.
  • Needs: —
  • Call: logged out → 401 with Log in that comes back · logged in, not a member → 403 with how to join.
  • Rules: —
  • Errors: E_AUTH (401) · E_PRIVATE (401) · 403.
  • Gotchas: Why: never a redirect, so a link opened in an app's viewer still lands.

project

A subdomain with its own members, topics and data. Also called: realm. Fields: name, level (Hero, Creator, Pro, Master — picked at creation, sets the templates: Home, Landing, Settings:PROJECT, working topics: Spec, and for Pro and Master SpecUi, Design, Implementation, SpecTest; ToDo:PROJECT…), version (three numbers), owner. Objects carry _d2 (realm, owner, times; stripped on read). Events: diesel.project.on.created, .on.joinRequested, .on.joinApproved, .on.joinDeclined, .on.invited, .on.inviteAccepted, .on.inviteDeclined, .on.roleChanged.

project_create

  • Summary: the person makes their first; a maker token may make more, within the plan.
  • When: your person wants another project.
  • Needs: a maker token for all their projects; a free name.
  • Call: check GET /api/v2/projects/available?name= → POST /api/v2/projects.
  • Rules: The first project is the person's own (d2welcome's next step); the AI connects afterwards from its home. Anyone but the Architect gets demo-<what they typed> (address too; base projects.prefix). Names starting d2 are the Architect's (start private); www, api, admin, auth, mail, status, cdn, root are reserved. Master needs the Monthly plan.
  • Errors: E_QUOTA → owned projects · E_PLAN → Master on Free · new addresses capped per week (certificates): the refusal says when it frees up.
  • Gotchas: —

project_release

  • Summary: an admin sets a higher version and rolls the logs over.
  • When: the project releases.
  • Needs: an admin.
  • Call: POST /api/v2/project/release.
  • Rules: —
  • Errors: —
  • Gotchas: —

project_demo

  • Summary: demos reset on every deploy and refuse a visitor's write.
  • When: working on d2hero, d2creator, d2pro, d2master, d2conf.
  • Needs: —
  • Call: the person's Reset all.
  • Rules: R-acct-7.
  • Errors: E_DEMO → log in, or use your own project.
  • Gotchas: —

plan

A person's subscription: Free, Yearly ($50/yr), Monthly ($20/mo). Quotas are per project, from its owner's plan (a member's own plan lifts nothing there); the Architect and d2 projects have none. Every number is in base Settings:Quotas (Architect-only), e.g. Free: 2 owned projects, 3 members, 300 objects, 10 domain classes, 20 files / 5 MB.

plan_change

  • Summary: only the person changes their own plan.
  • When: never by you; point your person to it.
  • Needs: —
  • Call: Plan page /account/plan (the provider's checkout; d2 never sees a card).
  • Rules: R-acct-4. Never another member either. The Architect can set anyone's plan and override one project's quotas.
  • Errors: —
  • Gotchas: —

plan_quotas

  • Summary: a write past a quota is refused; nothing stored is deleted.
  • When: a refusal names a quota, or you check headroom.
  • Needs: —
  • Call: the project's Quotas page: each limit, its use and source, read-only.
  • Rules: R-acct-5. Warnings at 70%, alerts at 85% and 100% to the project's admins (the Architect at 100%). A project already over keeps working but can't grow. All-projects AI tokens come with paid plans; on Free they work only on the project they were made on.
  • Errors: E_QUOTA (403) → names the quota and the plan that lifts it · E_PLAN (403) → a paid-plan feature on Free.
  • Gotchas: —

Rules

  • R-acct-8 Everything but users is isolated by project: topics, objects, sessions; a form post from another origin is refused.
  • R-acct-9 The Architect's pages (/razadmin, /razadmin/members) answer only the Architect's session, never a token.
  • R-acct-10 Rate limits: sign-ups 10 an hour per address, invites 30 an hour per inviter (rows of Settings:Quotas); the Architect hears of anyone over.

Errors

  • E_AUTH (401) — not logged in (a page) or no/bad token (the API) → log in; for an AI, d3-f-tokens › errors. see #account_me
  • E_FORBIDDEN (403) with need: <level> — role below what view/edit asks → an admin raises the role, or a mod changes the topic's access. see #member_role
  • E_PRIVATE (401) — a private project, no member session or token. see #session_denied
  • E_QUOTA (403) — a plan limit (projects, members, objects, classes, files) → tell your person; never work around it. see #plan_quotas
  • E_PLAN (403) — a paid-plan feature (all-projects token, a Master project) on Free. see #plan_quotas
  • E_DEMO — a visitor writing to a demo → log in, or use your own project. see #project_demo
  • E_LOCKED — too many wrong passwords → the person waits, or an admin unlocks. see #session_login
  • E_ORIGIN — a form post from another origin. see #session_login