Internals

Code layout#

A modular monolith: one process, one image, one database, four independent domains. CI fails on any import that crosses a boundary (bun run architecture).

   the browser ─┐
                ├─►  src/app/       the HTTP surface: thin handlers, one pipeline
   the gateway ─┘        │
                         ▼
              src/domains/     the rules, and only the rules
       identity │ authorization │ administration │ provider
                         ▲
                         │  the ports of the domains
              src/platform/     PostgreSQL, Redis, the Bun listener, the HTTP client
                         ▲
                         │
              src/runtime/       the composition root: the environment, the wiring

scripts/gates/architecture.ts (bun run architecture, also run by CI and test/architecture/) fails when:

1. a domain is imported other than through its index.ts;
2. one domain imports another;
3. core domain code imports Hono, a Bun API, an adapter, the application, the platform or the runtime;
4. the application reaches a concrete adapter instead of a domain entry point or observation interface;
5. the platform makes a policy decision or knows the application or runtime;
6. the observation layer depends on anything;
7. anything but the runtime (the composition root) assembles the parts;
8. a catch-all directory or an import cycle appears;
9. the framework leaves the application, or the runtime's API leaves the runtime platform;
10. anything but the runtime reads process.env.

test/architecture/no-scaffolding.test.ts asserts there is no SAML, console, SCIM or directory sync (§14). bun run dead runs knip, which names unreachable files and unused exports from the entry points in knip.json (tests, operator scripts) plus the service entry point; bun run dead --fix removes unused exports.

Flows. Login follows §5.4. A decision (POST /v1/decisions) authenticates the gateway, runs one statement over users, tenants, grants, permissions and groups under ACCESS_DECISION_TIMEOUT_MS, and answers {"allow", "reason"}. A concept spanning three layers has three files: the HTTP contract (src/app/decision-contract.ts), the rule (src/domains/authorization/decision.ts) and the facts the rule reads (src/platform/postgres/decision-facts.ts). Storage never decides; the domain never sees SQL.

Data model (§3). Every domain table carries tenant_id, and foreign keys are composite (id, tenant_id), so the schema stops a grant naming another tenant's principal. Row level security scopes every statement by the transaction-local access.scope and access.tenant_id; a statement with no scope sees nothing, and the scope of the platform is asked for by name (§3.10). Grants are the policy: permission, workspace, route, expiry. admin_audit, like the migrations table, is infrastructure and holds no domain row.

Working rules, beyond the platform rules:

1. Never modify the gateway, for a feature, a bug or a test.
2. The schema reserves nothing: no always-null column, empty table or unread flag.
3. Failure is denial everywhere; the service never guesses toward allowing.
4. Back every decision with a measurement, a test or a provider document.

Tests#

The rule that every rule needs a test is in platform internals.

bun run test runs units, contracts and boundaries, and needs neither the reference gateway nor a sibling directory. bun run test:integration runs the integration tests.

Documentation tests#

test/architecture/ also holds the documentation to the code, so a docs change can fail the build:

The root bun run api:check also compares the endpoints named in api.md with the routes and the OpenAPI description.

Databases in tests#

Tests run on the embedded database by default. A workflow with a server sets ACCESS_TEST_DATABASE_URL, and the same tests run against it. The repository is developed and tested against PostgreSQL 18: the development compose file, the CI jobs and the release gates run it, and the embedded PostgreSQL is that version.

Compatibility test#

The gateway starts with its own configuration, with its fixtures replaced by Access:

GATEWAY_OIDC_ISSUER   = the issuer of Access
GATEWAY_OIDC_CLIENT_ID= the client id of the tenant
GATEWAY_ACCESS_URL    = the base url of Access
GATEWAY_ACCESS_TOKEN  = the access token of Access

The suite asserts that:

1. a browser logs in at the tenant's provider and returns to the gateway with a session;
2. the gateway writes the x-gateway-user, x-gateway-email and x-gateway-roles headers with the principal's values;
3. a request with a grant on the workspace is forwarded, and one without is refused with 403 workspace_forbidden;
4. a revoked grant is refused within the gateway's cache TTL;
5. the gateway's metrics count the denial as missing_role.

A second file, test/compatibility/cutover.test.ts, rehearses a tenant cutover (Operations), playing the runbook phases against the reference gateway: register the tenant, its principal and its grant; a browser logs in and reaches an upstream; revoke the grant and access ends; switch the tenant again without registering anything.

The gateway is never modified for these tests. A test that needs a gateway change is refused: the compatibility test exists to prove none is needed.

Compatibility suite#

bun run --cwd packages/access test:compat runs the platform gateway, unchanged, against Access. The reference is the platform's packages/gateway/ workspace at the repository's revision, pinned in the root compatibility.json, the one place that names the workspaces (platform compatibility describes the manifest). The runner validates it strictly: version 2, the platform repository, only the three known workspaces, and a 40-hex commit (no branch) for a reference.

The runner (scripts/compat/compatibility.ts, bun run test:compat) is the only way the reference is prepared. A developer-prepared reference (ACCESS_GATEWAY_PATH) is checked and never written to; one that carries changes is refused with the reason. To test a published gateway revision, name a repository and a full commit id: a branch, tag, short hash or placeholder is refused, because a moving reference cannot be tested twice. A suite run against another revision proves nothing.

The runner reads the manifest from the repository root, clones the gateway at the pinned commit (from the local repository when it holds the commit, so no network), installs its dependencies, checks its tracked files, runs bun test test/compatibility with the path in ACCESS_GATEWAY_PATH (the suite runs the gateway as a process in its own directory), and checks the reference is still unchanged. Its last line names the tested commit: the compatibility suite passed against the gateway at <commit> ….

bun run compatibility runs it with the workspace tests and platform acceptance. Plain bun test also collects the suite, which then fails with instructions; use bun run test day to day.

Sources, first one set wins:

Options: COMPAT_WORKSPACE (checkout directory, default temporary), COMPAT_KEEP (keep the checkout), COMPAT_TESTS (space-separated test files). To test a running service such as a release image, set ACCESS_EXTERNAL_URL, ACCESS_EXTERNAL_ADMIN_TOKEN and ACCESS_EXTERNAL_ACCESS_TOKEN (its decision token); the suite then starts nothing of its own.

mkdir -p /srv/compat-mirror
git clone --bare https://github.com/ggpwnkthx/platform.git /srv/compat-mirror/gateway.git
COMPAT_MIRROR=/srv/compat-mirror bun run --cwd packages/access test:compat

An override that is set but unusable is an error; the runner never falls back. Temporary checkouts are removed on failure and interruption; a supplied one never is.

The blocking compatibility CI job runs bun run compatibility and checks all three reference trees against the manifest. release.yml reruns the suite against the published image by digest through ACCESS_EXTERNAL_URL.

Capacity#

scripts/ops/load.ts measures the production decision statement through the service's repository with the deployment deadline. It runs on every CI build against the job's PostgreSQL; numbers are in the build log. Only measured numbers are published.

ACCESS_DATABASE_URL=postgres://… bun run scripts/ops/load.ts --requests 5000 --concurrency 20 \
  --max-p50-ms=60 --max-p95-ms=90 --max-p99-ms=120 --min-per-second=100

Each --max-* option fails the run when that percentile exceeds it, --min-per-second when throughput is below it; without them the script only reports. CI thresholds sit far above the targets because runners are shared: they catch a changed plan, a dropped index or a policy-table scan.

The thresholds of the build are set from the measurement of the shared runner, not from the target: a shared runner has two cores and the pool of the service has ten connections, so twenty requests in flight measure the queue of the pool and not the statement. The runner measures a p50 of about thirty milliseconds at that concurrency, and the gate is twice the measurement. The documented target of a decision under load — a p99 of fifty milliseconds — is what the gate protects.

The tenant-decision gate allows a higher percentile than the platform-decision gate, because a tenant-scoped statement runs inside a transaction and costs about a third more. Both gates catch the same defects.

PostgreSQL 18 over loopback, 16-core development machine (load average one), 5 000 requests, 20 in flight, one principal with a hundred grants, median of three runs:

The columns are the two §8.8 schemes. Tenant credentials need a transaction for the transaction-local scope, which costs about a third more. Targets are met on this machine.

Embedded PostgreSQL (one connection), 1 000 requests: p50 0.45 ms, p95 0.57 ms, p99 0.64 ms, maximum 0.71 ms, 2 146 per second. With 20 in flight, p50 is 42.7 ms and p99 48.9 ms at the same throughput: the single connection's queue, not the query.

With 1 000 principals and 1 000 000 grants, for a principal holding a thousand, the plan is Bitmap Index Scan on grants_user_live with Index Cond: (user_id = u.id), executing in 1.5 ms.

Not measured yet: deployment-hardware numbers, pool saturation, memory under a thousand logins and broker overhead. They are measured with the same script during the first tenant's cutover and published here.

Security review#

Model: login state is encrypted, authenticated and single use; codes are opaque, hashed, single use and bound; decisions and administration compare credentials in constant time; the database enforces tenant rules; client secrets are encrypted with AES-256-GCM under a key derived with HKDF-SHA256 from the deployment secret.

Open findings#

Release readiness#

Someone who did not write the service checks each item; every answer is a test, a measurement or a document.

Checked on a deployment: capacity with scripts/ops/load.ts, pool saturation and memory on the dashboard, and alert wiring and image rollback by someone who did not write the service, all during the first cutover; restore and recovery times quarterly.

Release and delivery#

Tagging, dispatch and artifacts are platform-wide (platform internals). Access-specific points:

The version appears in five files, and bun run versions names any that disagree: packages/access/package.json, packages/access/Dockerfile (ARG VERSION), packages/access/src/runtime/version.ts, docs/access/spec.md (status) and docs/access/README.md. Bump them in one commit.

tag.yml is started by the push of the commit, waits for the CI of that commit, tags it with v<version> when the version went up, then dispatches the release workflows (a workflow-token push starts none). It refuses disagreeing versions, a pre-release version, and a version that went down; an unchanged version does nothing. Dispatch by hand with gh workflow run release.yml --ref v1.0.9 -f tag=v1.0.9 (and release-binaries.yml), or push a hand-made annotated tag, which starts the release directly.

Each archive holds the binary and migrations/ beside it (§3.8); embedded PostgreSQL ships in neither binaries nor image.

tar -xzf access-1.0.9-linux-x64.tar.gz -C /opt/access
/opt/access/access-1.0.9-linux-x64
trivy image --severity HIGH,CRITICAL --exit-code 1 access:ci
syft access:ci -o spdx-json > access.spdx.json

A change merges on green CI with one reviewer other than the author, and with the spec updated when a rule changed.

Support policy#

A release is supported while current and for one release after: deployments on N move to N+1, and N is not patched after that. Patch releases never change behavior; a contract change updates the spec with the code and is a minor release. The current release is the package.json version and tag v<version>, tested against the repository's gateway revision. Changes are in CHANGELOG.md.

Known limits#

Deferred features (SAML, console, SCIM, directory sync, account linking) are in §14; none has a column, table, flag or endpoint, and a test asserts it.