Security in Artist Alley
Artist Alley holds three classes of valuable data: artists’ creative work (often confidential, often NDA-bound), studio metadata (project names, internal review comments, unannounced IP), and operator credentials (auth, third-party API keys, license signing material). The security posture is built around protecting all three from accidental exposure and from determined attackers with credentialed access.
This page documents the load-bearing rules. Any PR that touches an authentication path, a credentials store, a permissions check, an asset-bytes path, or an external integration follows them.
Threat model
Section titled “Threat model”Three concrete adversaries shape the design:
- The credentialed but unprivileged user. A user with a valid login but no business reading restricted assets. The attacker the permission system is built against.
- The leaked credential. A stolen session, a published API token, a misplaced license file. Mitigation is revocation and an audit trail: sessions expire after a period of inactivity and can be revoked, API tokens can be given an expiry and revoked at any time, and sign-ins and security-relevant changes are audited. API tokens don’t expire unless their creator sets an expiry, and a token’s scope list doesn’t limit what it can do yet (see Authentication).
- The compromised peer / connector / add-on. A federated peer, an import source, a third-party plugin running malicious code. The design aim is that each is trusted only as far as an explicit decision allows. For federation, pairing shares nothing: a new pairing request waits for an administrator to accept the offered key, and activities about a post go only to peers it has been explicitly shared with. The initial pairing handshake is self-signed rather than sent as an HTTP-signed request. Known gaps remain: federated messages are authenticated per instance, not per actor, because per-actor signatures are not created or verified yet; a receiving instance doesn’t yet check that the sender holds a share grant for the object; and the sender’s refusal to send restricted or embargoed content unencrypted isn’t wired up. See ArchivePub’s What works today. Add-ons are planned, so there is no plugin isolation boundary to rely on yet.
Not in scope:
- Nation-state targeting. Out of scope for the project’s threat model; operators with that risk profile run their instance behind air-gapped infrastructure.
- Physical access to the server. If the attacker can read disk, all bets on data confidentiality are off; disk-level encryption is the operator’s responsibility, not ours.
- Side-channel attacks against the host OS. Speculative execution, hardware-level RNG bias, etc. Out of scope.
Authentication
Section titled “Authentication”- Sessions are server-side. The
sessionstable holds a SHA-256 digest of the token; the client gets an opaque cookie carrying the plaintext, which never reaches the database. There is no client-readable session payload. - API tokens are Personal Access Tokens, prefixed
aa_pat_: random high-entropy strings. Only their SHA-256 digest lands inapi_tokens.token_hash; the plaintext is shown once at creation and never persisted, so a database dump yields no usable tokens. A token has an optional expiry and can be revoked at any time. It can also be given a scope list, but scopes are recorded, not enforced yet: a token currently acts with the full permissions of the user who created it, so treat every token as a full credential for that account. A token can only be created from a cookie session; you can’t mint one using another token. - Passwords are peppered with HMAC-SHA256 (keyed by
AA_SCRAMBLE_KEY) and then hashed with bcrypt. The pepper means a stolen database alone can’t be cracked offline without also holding the scramble key. Plaintext passwords must never be written to logs, audit events, or response bodies; any path that does is a bug. There is a deliberate exception for the first-boot administrator: when no administrator exists yet, the server generates a random password, prints it in the startup log and tries to write it tobootstrap-admin.txtwith mode 0600. If that write fails, the log is the only copy. Protect any startup log that contains it, and change the password after the first sign-in. - SSO isn’t available yet. The code has LDAP and SAML providers, but they only register with a license feature that can’t be obtained today, and there is no OAuth or OIDC provider. Generic SSO is planned for v0.17.0 and will not need a license (ADR 0066); provider-specific bridges (Okta / Auth0 / WorkOS) are planned as add-ons per ADR 0038.
Authorisation
Section titled “Authorisation”- Capability codes are the unit of permission, not role names. Code that checks “is this user an admin” is wrong; code that checks “does this user have the
assets.deletecapability” is right. - Capabilities live in the
capabilitiestable; roles bundle capabilities viarole_capabilities; users get roles viauser_roles. Per-user overrides (user_capability_grantsanduser_capability_revokes) let an admin grant or revoke a specific capability without inventing a one-off role. - The capability check happens at the handler entry, not deeper. A repository method does not check capabilities; the handler that calls it does. This keeps the trust boundary visible.
These are the rules new code follows. They are not a guarantee that every existing endpoint already applies a capability check: some endpoints currently check only that the caller is signed in.
Asset sensitivity
Section titled “Asset sensitivity”Partly shipped; the rest is planned for v0.15.0 (ADR 0020). Assets carry a sensitivity tier today. A restricted or embargoed asset still appears as a locked placeholder on post pages and in collections (the default feed hides it): its title, fields and thumbnail are withheld from readers without access, who can request access, and the routes that deliver the asset’s content by asset ID refuse to serve it to them. Server-side blur, the
Revealaction and the embargo card described below are planned.
- Per-asset sensitivity tier, shipped (
public/team/restricted/embargo, per ADR 0020). The tier is enforced on the server, not just in the UI, by the routes that deliver an asset’s content by asset ID: its original file, derived variants, video streams and archive contents are served only after the caller’s access, including the tier, has been checked. - Planned for v0.15.0: server-side blur for restricted and embargo assets. Blur would be a preview variant generated server-side, so even an unauthenticated network-tap leak shows blurred bytes, and a
Revealaction would lift the blur for the session and write an audit event. - Planned for v0.15.0: embargo lift via the scheduled-action engine. The lift would be a timed action, audit-logged when it fires.
Secrets handling
Section titled “Secrets handling”- Encryption at rest. The host master key,
AA_MASTER_KEY(required at boot), encrypts selected sensitive values in the database: two-factor (TOTP) secrets, federation identity, actor and user keys, and the SMTP password. Not every secret entered in the admin settings is encrypted this way, so treat the database and every backup of it as sensitive: restrict who can connect to it, and keep backups encrypted and access-controlled. Stored credentials are never returned by the admin API. - Master key rotation isn’t supported in v1: there is no tool to re-encrypt existing values under a new key, so keep
AA_MASTER_KEYstable and backed up. - Cloudflare Worker Secrets will hold the Ed25519 signing key for license
.licissuance (once licensing ships, planned for v0.18.0, per ADR 0017); the signing key never leaves the Worker.
Audit trail
Section titled “Audit trail”- Security-relevant changes write an
audit_eventsrow: sign-ins (succeeded, failed, rate-limited), account lockouts, sessions expiring or being revoked, capability grants and revokes, access requests, scheduled actions, federation shares, admin asset deletes and restores, admin configuration changes, and audit retention purges. Recording is best-effort: an operation may have no audit entry if recording fails. - Events are not yet linked by a shared request or job identifier. Each event records its type, time, and event-specific metadata, plus the actor, subject, IP address and user agent where they’re available. Those can be absent, particularly for work the system starts itself.
- Audit retention defaults to 7 years. Admins can export the audit log as CSV or newline-delimited JSON; the export is not signed. Signed export is planned with the licensing work (ADR 0017).
Share links
Section titled “Share links”Planned for v0.15.0. The design below (ADR 0018) is the intended posture; share links are not yet shipped.
Signed, expiring share URLs for external collaborators (per ADR 0018):
- Token is a 32-byte random ID, not a JWT. Revocation is a single-row delete: no key rotation, no token-blacklist surface.
- Per-link scope:
view/comment/annotate/download. Scope is enforced at the handler; bypassing the link viewer to hit the canonical endpoint still requires the matching capability. - Optional password on the link, stored hashed. Failed-password attempts are rate-limited and audited.
- Per-fetch audit trail: IP, user-agent, password-result, scope satisfied. The operator can see who’s used a link without contacting the recipient.
Input handling
Section titled “Input handling”- Request decoding and handler checks. Requests are decoded into the types generated from the OpenAPI spec, and a request body that can’t be decoded is rejected with a 400; beyond that, handlers apply their own validation where it applies. There is no separate OpenAPI schema-validation middleware mounted.
- No SQL string concatenation. Use the parameterised queries sqlc generates; where a query has to be built at run time, pass values as parameters rather than formatting them into the SQL string. Raw
db.Exec(fmt.Sprintf(...))is a code-review block. - No HTML concatenation in templates. Svelte’s auto-escaping is the default;
{@html ...}is a code-review block requiring justification. - Path traversal: stored files are addressed by key, not by a path the caller supplies. The storage layer validates every key before a backend touches it: the object name must be a SHA-256 hash, and a variant key may not contain
.., a leading slash or a doubled slash. Both storage backends run this check on every operation, so handlers don’t repeat it.
Privacy and consent
Section titled “Privacy and consent”Per ADR 0024:
- Soft delete first (shipped): deleted assets, posts and collections stay recoverable for 30 days by default, and archived users for 90 days, before they become eligible for hard delete. Operators can change these retention periods.
- Cookie / tracker banner, planned for v0.16.0, will render only when a non-essential category is in use; a bare studio install with no analytics shows no banner.
- DSAR tooling, planned for v0.16.0: every user will be able to export their personal data as JSON and request deletion; hard delete reassigns authored content to a
deleted-usertombstone so collaborative work survives. - Audit-log access is itself capability-gated. Reading the audit log is not itself recorded as an audit event.
Reporting a vulnerability
Section titled “Reporting a vulnerability”If you believe you’ve found a security issue:
- Do not open a public GitHub issue. Report it privately: open a private security advisory from the repository’s Security tab (Report a vulnerability), or email
security@artist-alley.org. - Include reproduction steps, the version affected, and the impact you observed.
- We’ll acknowledge your report and keep you informed while we investigate and work on a fix.
We don’t run a bug bounty programme yet. Public credit for the report (your choice, opt-in) lands in the release notes for the fix.
Things that look like security features but aren’t
Section titled “Things that look like security features but aren’t”- Anti-AdBlock. There’s no ad add-on today, and the plan is not to fight ad blockers; we don’t arms-race against them from the AGPL core.
- DRM on asset bytes. We do not encrypt asset bytes at rest within the storage backend beyond what the backend itself provides (S3 server-side encryption is an operator-configured option, not an Artist Alley feature). DRM-protected delivery is out of scope.
- Anti-account-sharing. Once licensing ships (planned for v0.18.0, ADR 0017), active seats will be counted for licensing, not surveillance: purely “how many distinct users have been active in the last 30 days”; we don’t fingerprint sessions, don’t device-bind logins.