Actions and resources

Every protected method asks Better IAM one question: may this caller perform this action on this resource in this tenant? Actions are written compute:<area>:<verb>, such as compute:reservations:create. Resources are written <type>/<id>, such as compute-pool/{poolId}. Both come from compute's catalog, which the bridge installs into every Better IAM host through bridge.plugin(), and they are the names you write policies against.

Resource types

All of compute's resource types are app-owned: nothing is ever registered in Better IAM. When IAM needs a resource, it calls compute's resolver, which answers from the memory-resident authz projection. The prefix is compute- by default; typePrefix changes it (it must match ^[a-z][a-z0-9-]{0,31}$) and must be the same in betterCompute() and createComputeIamBridge().

Besides a row's attributes, every resolved resource carries ownerId when the row has an owner, and the prefixed parentType and parentId of its parent. Better IAM turns the parent into resource.parentRelations, so a policy on a reservation can test the caller's relations on its pool. The attributes each row actually carries today are listed under Resource attributes.

Scope types

Three types exist only as scopes, so a decision about "everything in this tenant" or "the whole fleet" has a resource to name:

• compute-fleet/global resolves only in the root tenant. Fleet-wide methods are decided in the root tenant, whatever tenantId their input names.
• compute-tenant/{t} resolves only when its id is the decision's tenant.
• compute-project/{id} resolves in the project's owner tenant.

How the resolver answers

The resolver runs inside Better IAM's locked decision transaction, so a hit must do no I/O:

• It echoes { tenantId, type, id } exactly. Better IAM refuses anything else as RESOURCE_MISMATCH.
• A row missing from memory costs one primary-key read, bounded to 20 ms. A row that does not exist is NOT_FOUND, which Better IAM does not audit and which aborts a whole authorizeMany batch.
• A lookup that times out, or a projection that is not loaded yet, denies (ACCESS_DENIED).
• Types without compute's prefix go to the hostFallback you passed to bridge.resolveResource(), or fail with RESOURCE_RESOLVER_REQUIRED.

Each process loads the projection at start and then tails authz_changes about once a second. Staleness can cause a spurious denial, never a wrong mutation, because compute re-validates inside its own transaction.

Admissions never decide on a stale copy. After an admission's first transaction commits the draft (or the changed row, as in reservations.extend), the envelope calls the optional IamPort.refreshResource(tenantId, resource) before iam.require. The embedded port from bridge.embedded() implements it with AuthzProjection.refresh(type, id, tenantId), which re-reads that one row; on a miss or a failed read it drops the row, so the decision takes the bounded miss path above and fails closed. Before this, reservations.extend decided on the row cached at creation, so a BoundedExtend-style policy capped at 72 hours could be passed by one extra hour within the tail interval. tests/server-example-policies.test.ts runs the example policies against real drafts to hold this.

In remote mode the IAM host decides on its replica's copy, so pass refresh: { url, secret, sql? } to bridge.remote() (or remoteIam(), which it wraps): the port then posts a signed { tenantId, type, id, lsn } to the IAM host's refresh handler (computeIamHost().refreshHandler), which waits at most 2 seconds until its replica has replayed compute's WAL position from after transaction 1 and re-reads the row. Any failure fails the admission with UNAVAILABLE (fail closed). Without refresh the remote port has no refreshResource, remote admissions can decide on a row up to the replica lag plus 1 second old, and better-compute doctor warns iam.refresh.

The remote port forwards only identity and client-context headers with the caller's credential (authorization, cookie when there is no bearer, origin, user-agent, x-request-id), never the client's own x-forwarded-for, x-real-ip or forwarded (e7092bf, security review 14 L3): behind a proxy that appends to them, a caller could choose the request.sourceIp its policy conditions see. The address IAM sees is Credential.sourceIp, which the host verified and the port sends as x-forwarded-for. compute.nodeHandler sets it from the socket's peer address; a fetch host passes it as compute.handler(request, { peer: { address } }) (d269738), from the socket or from the hop a proxy it trusts reported. Without it IAM sees no source address. See hosting the API.

Actions

The core catalog declares 56 actions. Most areas have a read action and a manage, create or finer verb. Where an action appears on a scope type as well as on an item type, the scope form gates list and create calls and the item form gates calls on one resource:

Adding actions

Modules and plugins extend the catalog with a catalog fragment, which createComputeIamBridge() merges into the types above. The built-in modules add none: the core catalog covers all of their methods. The merge enforces Better IAM's limits and fails with INVALID_CONFIG on a breach:

• An action matches ^compute:[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)+$. A plugin's actions must start with compute:<pluginId>:.
• A type has at most 64 attributes and 32 relations, and its name at most 64 characters. Attribute types are string, number or boolean.
• Two fragments may not disagree on a type's parent or on an attribute's type. A parent must be in the catalog.

import { definePlugin } from 'better-compute/core';

export const acmeAutoinstall = () =>
  definePlugin({
    id: 'acme-autoinstall',
    catalog: {
      // Merged into compute-node; plugin actions live under compute:<id>:.
      resourceTypes: { node: { actions: ['compute:acme-autoinstall:render'] } },
    },
    // api(context) { ...methods that declare action 'compute:acme-autoinstall:render' }
  });

Pass the plugin to both betterCompute({ plugins }) and createComputeIamBridge({ plugins }), so the API and every IAM host agree. initialize() checks the method registry against the merged catalog: a method whose action is missing (uncatalogued) or that disagrees with its method-table row (mismatch) fails with INVALID_CONFIG, and a non-plugin method with no row (undeclared) is a catalog.undeclared warning in better-compute doctor. See Modules and Methods.

Method-to-action table

This table is rendered from the live method registry. The normative source is PLAN.md §9.2, kept as apiSurface in @better-compute/core: scripts/authz-matrix.mjs generates one test per row, and tests/iam-bridge-matrix.test.ts checks every action and type pair against a real Better IAM carrying the bridge, allowing each only when granted. It decides through compute's own IamPort: bridge.embedded under pnpm test, and bridge.remote over the IAM's HTTP API under pnpm test:iam-remote.

• Decided on is the resource type of the one decision. Its id comes from the input: the pool for compute-pool, the tenant for compute-tenant, global for compute-fleet.
• or means the method decides on one of two resources depending on its input. For example, sites.create decides on compute-fleet for shared and dedicated sites and on compute-tenant for a tenant's custom site, and usage.list decides on compute-project when the input names a project.
• + items marks a list that follows the list recipe.
• planned marks a method this release does not serve yet; it arrives in the phase shown.

Platform and tenancy

Nodes and access

Capacity

Usage and events

Provisioning and bare metal

VPS

Fleet and rollouts

How a call is decided

The envelope in @better-compute/server runs the same steps for every method, over HTTP (POST /api/compute/<group>/<method>), the typed client and compute.api.<group>.<method>(credential, input):

1. Public methods (system.whoami, system.version) validate their input and run.
2. A call without a credential is UNAUTHENTICATED, with no IAM call.
3. The input is validated (INVALID_INPUT) before any IAM call.
4. IamPort.authenticate identifies the caller. The answer is cached for 30 seconds.
5. The tenant pre-check below runs.
6. Methods with an admission (request-as-resource creates, reservations.extend, and creates that take an idempotency key) run prepare in a first transaction: the idempotency lookup and the draft and projection rows, never an IAM call. A replay by the same caller returns the stored result without a decision. Otherwise the one decision is require on the resource prepare returned.
7. Every other mutation makes one require, never cached. A read makes one authorize, whose allows are cached for 10 seconds per session.
8. The handler runs in one transaction, read-only for reads. An allowed mutation also writes an audit_events row with its admission context in that transaction.

IAM is never called inside a compute transaction. Denials are opaque: Better IAM reports every denial as ACCESS_DENIED, including a host without the plugin answering UNKNOWN_ACTION, and compute adds nothing to it.

Cross-tenant refusal

A caller whose tenant is neither the input's tenantId nor the root tenant gets ACCESS_DENIED before compute reads or writes its database and before any IAM decision. For fleet-wide methods, the decision tenant is the root tenant, so only root-tenant callers pass.

The check was added because Better IAM 0.1 resolved the resource before it checked the tenant: without it, an outsider probing ids got NOT_FOUND for ids that do not exist and ACCESS_DENIED for ids that do, an existence oracle, and every probe appended a denial to the victim tenant's audit chain. Better IAM 0.2, which Better Compute now requires, checks the tenant first itself: a foreign tenant is denied (TENANT_MISMATCH, masked as ACCESS_DENIED) before any resolver runs, absent and present ids get the same answer, and the denial is audited on the caller's own tenant with the target in targetTenantId (pinned by tests/iam-contract.test.ts). Compute keeps its own check anyway: the answer is the same in every case, and an outsider costs no database access and no IAM decision. tests/server-admission.test.ts asserts that such a call makes one IAM call (authenticate) and no database access at all.

Root-tenant callers continue to IAM, which allows them into another tenant only through ROOT_OVERRIDE: a root-tenant person with root authority, in a user session with MFA. Better IAM audits every override. Inside your own tenant, an id that is not in your view resolves to NOT_FOUND, which reveals nothing beyond the tenant.

List methods and item filtering

The methods marked + items return only the rows the caller may read, without one IAM round trip per row:

1. Coarse gate. The envelope's one decision on the scope, compute-tenant/{t} or compute-project/{id}.
2. SQL pre-filter. The query is scoped to the tenant and to rows the projection holds in that tenant's view.
3. Owner-scoped kinds. reservations.list and instances.list take scope: 'mine' | 'all', and mine is the default: the coarse decision plus owner_identity_id = caller in SQL, with no per-item checks.
4. Everything else, including scope: 'all', pools.list, nodes.list, sites.list, projects.list, profiles.list, images.list and providerAccounts.list: after the page is read, every item is decided with the method's action on its own resource. Allows already in the read-decision cache are reused; the rest go in authorizeMany batches of at most 50.

// The caller's own reservations: one decision on compute-tenant, no per-item checks.
const mine = await compute.api.reservations.list(credential, { tenantId });

// Every reservation the caller may read in the tenant: per-item checks in batches of 50.
const all = await compute.api.reservations.list(credential, { tenantId, scope: 'all' });

A batch never degrades into a partial list. When the resolver does not know an item yet (NOT_FOUND aborts the whole batch), compute waits 100 ms for the projection to catch up, reloads the page and retries once. Any other batch error fails the request, and an answer whose length does not match the batch is INTERNAL_ERROR.

Every denied item costs an audit write: Better IAM appends a denial to the tenant's audit chain, under its global lock. Write policies so that list pages mostly allow, and prefer scope: 'mine' where it answers the question.

Caches

Both caches hold at most 10 000 entries, least recently used first out. Mutations are never cached. The server exposes invalidation as compute.caches: dropIdentity(identityId), dropSession(sessionId), dropDecisions(), clear() and stats(). Every drop also discards answers that were in flight when it happened, so a revocation cannot be overwritten by an older allow. Wire these to IAM events as shown in IAM integration.