Documentation

Flametrench v0.2

This is the documentation for the Flametrench specification and the reference SDKs. The spec is the source of truth; every SDK conforms to it or it is not a Flametrench SDK.

Specification chapters

• Identifier format — wire format, storage format, type prefix registry, encoding & decoding rules, conformance fixtures.
• Identity — opaque users (usr_), credentials (cred_: password/passkey/OIDC with Argon2id pinned), user-bound sessions (ses_) with rotation.
• Tenancy — flat organizations (org_), memberships (mem_) as duals of auth tuples, invitations (inv_) with atomic acceptance, self-leave vs admin-remove procedures.
• Authorization — relational tuples (tup_) as the sole authz primitive, exact-match check() semantics, the six built-in relations.

Conformance

• How SDKs are verified — language-agnostic JSON fixtures, RFC 2119 conformance levels, drift-checked in CI. How third-party implementations prove they conform to the spec.

Supporting artifacts

• Architecture Decision Records — the why behind every load-bearing choice across v0.1 and v0.2.
• Reference Postgres schema — non-normative DDL that encodes the current data model (v0.1 + v0.2).
• OpenAPI specification — the HTTP contract every conforming server exposes.

In v0.2

• Authorization rewrite rules — computed_userset (role implication) and tuple_to_userset (parent-child inheritance), with depth/fan-out caps and direct-match short-circuit.
• Multi-factor authentication — TOTP (RFC 6238), recovery codes, and WebAuthn assertion verification across ES256 / RS256 / EdDSA.
• Share tokens (shr_) — time-bounded, presentation-bearer access to a single resource without minting an authenticated principal.
• Postgres-backed reference adapters — PostgresIdentityStore, PostgresTenancyStore, PostgresTupleStore, PostgresShareStore across all four SDKs.
• Organization metadata (name + slug) and invitation acceptance binding (security).

Coming in v0.3+

• Admin UI reference implementation.
• Audit events (aud_), notifications (not_), file metadata (file_).
• Feature flags (flag_) and billing hooks (sub_).
• Magic-link and SAML credential types.
• Nested organizations.
• Additional language SDKs as adopter demand emerges.

Track progress or open a discussion at github.com/flametrench/spec.