ad9210b84a
Secure Send shipped on 21 August and nothing outside the code caught up. The roadmap still listed it under Deferred as "tabled", and gave as the reason that the tools plugin is browser-only by design with get_blueprint and get_models both empty - which stopped being true in the same day's commits that gave it a blueprint, a table, a migration chain, a permission and a setting. A reader following the roadmap would have concluded the feature does not exist. The generated API docs were fine: api-inventory.json and openapi.json both carry /api/tools/secrets, so the contract gates did their job. What was missing was every word written for a person, and that is the half where the security properties live. docs/SECURE-SEND.md is the new page. The parts worth having in prose rather than inferring from the code: that a lost secret is lost to everybody including an administrator, which is the same property as "a compromised database yields nothing" seen from the other side; that the 4096-character limit is the entire server-side enforcement, because a server that cannot read what it holds cannot have an opinion about content, so raising it turns a password tool into an unaudited file transfer; that redeeming is a POST because preview prefetch in chat and mail clients would otherwise spend a one-view secret before the recipient ever sees it; and that somebody should send a link to themselves through their own mail or chat client and confirm the key survives after the # before a real credential goes through it, because a product that rewrites links can strip the fragment and nothing on this side can help. securesend_allow_guests was in the database, on a settings page, and in no document. It is now in CONFIG.md with what it actually does - an unauthenticated write endpoint, rate limited per address, failing closed - rather than only its one-line description. Also corrected along the way: site_base_url was documented as scheme + host while the code deliberately tolerates a subpath in it, and the bundled plugin table in PLUGINS.md had no row for tools at all. Still missing after this: PLUGINS.md has no row for backups either.
80 lines
3.5 KiB
Markdown
80 lines
3.5 KiB
Markdown
# Start here
|
|
|
|
ShopDB is a per-site asset platform: one instance per plant, plugins for what
|
|
each site tracks. These pages document the server, the plugin contract, and the
|
|
tools that run on shop-floor PCs.
|
|
|
|
Find yourself below. Each row is the shortest correct path, not everything that
|
|
exists.
|
|
|
|
## I am standing up ShopDB at a new site
|
|
|
|
1. [INSTALL-WINDOWS](INSTALL-WINDOWS.md) - one offline installer, start to finish.
|
|
2. [OPERATE-WINDOWS](OPERATE-WINDOWS.md) - restart, logs, backups, upgrades.
|
|
3. [CSV-IMPORT](CSV-IMPORT.md) if the site's data is in spreadsheets, or
|
|
[IMPORT-API](IMPORT-API.md) if there is a source database to script against.
|
|
4. [FLOOR-MAP](FLOOR-MAP.md) - load the site's floor plans and place markers.
|
|
Also the page to read BEFORE a plan changes: it covers moving every marker
|
|
onto a redrawn plan without doing it one at a time.
|
|
|
|
**Do not** follow [INSTALL-WINDOWS-IIS](INSTALL-WINDOWS-IIS.md) for a new site.
|
|
That is the manual procedure, kept for hand-built servers that predate the
|
|
installer, and following it produces a server the installer then refuses to
|
|
upgrade.
|
|
|
|
## I am deploying the shop-floor tools
|
|
|
|
Read [FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) first - it is one page and it
|
|
is what makes the rest make sense.
|
|
|
|
Then [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md), which has worked
|
|
examples for Intune, GE-Enforce and manual installation, and says where each
|
|
artifact comes from.
|
|
|
|
## I am writing a plugin
|
|
|
|
1. [PLUGIN-QUICKSTART](PLUGIN-QUICKSTART.md) - scaffold and first run.
|
|
2. [PLUGIN-HOOKS](PLUGIN-HOOKS.md) - the contract. Authoritative.
|
|
3. [PLUGIN-LAB-PRINTEDPARTS](PLUGIN-LAB-PRINTEDPARTS.md) - a real plugin built
|
|
end to end, to type along with.
|
|
4. [PLUGIN-EXTERNAL-REPO](PLUGIN-EXTERNAL-REPO.md) if it lives in its own
|
|
repository, and [CONTRACT-STABILITY](CONTRACT-STABILITY.md) before you choose
|
|
a version pin.
|
|
|
|
## I am integrating with the API
|
|
|
|
1. [LLM-GUIDE](llms.txt) (`docs/llms.txt` in the repo, also served at
|
|
`/api/docs/llms.txt`) - auth, the response envelope, common recipes.
|
|
Short, and the envelope section is the part people get wrong.
|
|
2. `GET /api/docs` on any running instance - the full spec, browsable.
|
|
3. [API-REFERENCE](API-REFERENCE.md) for prose, [COLLECTOR-INTEGRATION](COLLECTOR-INTEGRATION.md)
|
|
if you are feeding data in from a PC.
|
|
|
|
## I have to give somebody a password
|
|
|
|
[SECURE-SEND](SECURE-SEND.md) - a one-view expiring link, instead of a chat
|
|
message or a sticky note. Read the "Before anybody relies on it" section first:
|
|
there is one thing to test at your site before the first real credential goes
|
|
through it.
|
|
|
|
## I am trying to understand why something is built this way
|
|
|
|
[The ADRs](adr/ADR-001-asset-as-platform-contract.md). They are the decision record,
|
|
they say what was rejected and why, and they are the fastest way to avoid
|
|
relitigating a settled question. [PROJECT-MAP](PROJECT-MAP.md) lists them all
|
|
with their status, along with the current versions and every migration head -
|
|
it is generated, so it is never stale.
|
|
|
|
## Something is broken
|
|
|
|
- Server: [OPERATE-WINDOWS](OPERATE-WINDOWS.md), then `shopdb-admin.ps1 check -Json`.
|
|
- A PC or a bay: the symptom table at the end of
|
|
[FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) says which piece to open first.
|
|
- A deploy that half-worked: [UPGRADE](UPGRADE.md) and
|
|
[BACKUP-RESTORE](BACKUP-RESTORE.md).
|
|
|
|
## I am moving a site to a different server or stack
|
|
|
|
[MIGRATE-TOPOLOGY](MIGRATE-TOPOLOGY.md) - Windows/IIS to Docker, Docker to a new
|
|
host, and back. The data moves cleanly; the URL the fleet points at is the work.
|