Security and access

Declare your security posture as seven lists. Handlers hold business logic only.

Package overview

Anyone building a service on our request shape: one declared matrix of routes and factors, enforced by one pipeline whatever the framework. Imports no sibling at all, so it can be adopted on its own. Supported runtimes: bun, node, workers, deno. Package root: @forgezero/access. Consumer documentation is curated with each module's explicit public flag; the complete internal/export inventory remains in the typed SSOT and declaration files.

bun add @forgezero/access

ForgeZero package family

The five packages are installation boundaries. Choose a package by who installs it; choose a subpath by the capability used in that file.

| package | short description | runtimes | documentation | |---|---|---|---| | @forgezero/vault | Scoped secret access with Agent, API-key and systemd-credential sources. | bun, node, workers, deno | Open | | @forgezero/access | Typed route, principal, factor, RBAC and request-pipeline contracts. | bun, node, workers, deno | Open | | @forgezero/providers | Typed external providers with priority, health and classified fallback. | bun, node, workers, deno | Open | | @forgezero/runtime | Portable runtime primitives for queries, jobs, events, schemas and finance. | bun, node | Open | | @forgezero/agent | Operator CLI and managed-node agent for bootstrap, deploy and lifecycle. | bun, node | Open |

@forgezero/access supported imports and commands

These are supported consumer entry points, not every internal module shipped for ForgeZero managed installation. Each row links to its task-oriented usage.

| public entry | short description | runtime | details | |---|---|---|---| | @forgezero/access | Declare routes, factors and policies as orthogonal lists; authorise against them. | portable | Reference + usage | | @forgezero/access/conditions | The twelve guards every project writes into before, each with the status its refusal deserves. | portable | Reference + usage | | @forgezero/access/effects | Audit, emit, meter, invalidate and notify — what happens after a request is decided, never failing it. | portable | Reference + usage | | @forgezero/access/security | Constant-time comparison, CSPRNG tokens, HMAC, HKDF, AES-GCM sealing and redaction. Web Crypto only. | portable | Reference + usage | | @forgezero/access/rate-limit | Request counters over a window — in memory, in Redis, or in a Durable Object. | portable | Reference + usage | | @forgezero/access/fetch | A Fetch-native adapter over the declared access pipeline. | portable | Reference + usage | | @forgezero/access/pipeline | The framework-neutral route, principal, factor, policy, rate-limit and effects pipeline. | portable | Reference + usage | | @forgezero/access/elysia | Elysia integration over the same access pipeline and route declarations. | portable | Reference + usage | | @forgezero/access/client | Typed client helpers that fulfil factors without duplicating the security matrix. | portable | Reference + usage | | @forgezero/access/testing | Deterministic access-pipeline fixtures and assertions for consumer tests. | portable | Reference + usage | | @forgezero/access/header | Strict configurable header-identity extraction with canonical names and bounded values. | portable | Reference + usage | | @forgezero/access/principal | Generic principal-source resolution for browser, API-key, attestation or future identity adapters. | portable | Reference + usage | | @forgezero/access/principal-session | Short-lived scope-bound delegated-principal sessions with sliding and absolute expiry. | portable | Reference + usage | | @forgezero/access/authenticator | Authentication-source contracts for adding identity mechanisms without changing route policy. | portable | Reference + usage | | @forgezero/access/ceremony-modes | Named security-ceremony modes and their session/action fulfilment semantics. | portable | Reference + usage |

Commands

bun add @forgezero/access — Install the framework-neutral access contracts and adapters.

bun add @forgezero/access

@forgezero/access

Declare routes, factors and policies as orthogonal lists; authorise against them. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  AccessError,
} from '@forgezero/access';

@forgezero/access — Declare routes before handlers

Routes and their access policy are data; Fetch and Elysia adapters enforce the same declaration.

import {
  defineRoutes,
  action,
  page,
} from '@forgezero/access';

export const routes = defineRoutes({
  orders: page('Orders'),
  'api/orders': action('List orders', 'GET', { page: 'orders' })
});

@forgezero/access/conditions

The twelve guards every project writes into before, each with the status its refusal deserves. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  assertDeclaredRefusals,
} from '@forgezero/access/conditions';

@forgezero/access/conditions — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  assertDeclaredRefusals,
} from '@forgezero/access/conditions';

export const selectedCapability = assertDeclaredRefusals;

@forgezero/access/effects

Audit, emit, meter, invalidate and notify — what happens after a request is decided, never failing it. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  audit,
} from '@forgezero/access/effects';

@forgezero/access/effects — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  audit,
} from '@forgezero/access/effects';

export const selectedCapability = audit;

@forgezero/access/security

Constant-time comparison, CSPRNG tokens, HMAC, HKDF, AES-GCM sealing and redaction. Web Crypto only. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  fromBase64Url,
} from '@forgezero/access/security';

@forgezero/access/security — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  fromBase64Url,
} from '@forgezero/access/security';

export const selectedCapability = fromBase64Url;

@forgezero/access/rate-limit

Request counters over a window — in memory, in Redis, or in a Durable Object. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  durableObjectStore,
} from '@forgezero/access/rate-limit';

@forgezero/access/rate-limit — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  durableObjectStore,
} from '@forgezero/access/rate-limit';

export const selectedCapability = durableObjectStore;

@forgezero/access/fetch

A Fetch-native adapter over the declared access pipeline. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  compileRoute,
} from '@forgezero/access/fetch';

@forgezero/access/fetch — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  compileRoute,
} from '@forgezero/access/fetch';

export const selectedCapability = compileRoute;

@forgezero/access/pipeline

The framework-neutral route, principal, factor, policy, rate-limit and effects pipeline. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  createPipeline,
} from '@forgezero/access/pipeline';

@forgezero/access/pipeline — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  createPipeline,
} from '@forgezero/access/pipeline';

export const selectedCapability = createPipeline;

@forgezero/access/elysia

Elysia integration over the same access pipeline and route declarations. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  elysia,
} from '@forgezero/access/elysia';

@forgezero/access/elysia — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  elysia,
} from '@forgezero/access/elysia';

export const selectedCapability = elysia;

@forgezero/access/client

Typed client helpers that fulfil factors without duplicating the security matrix. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  buildPath,
} from '@forgezero/access/client';

@forgezero/access/client — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  buildPath,
} from '@forgezero/access/client';

export const selectedCapability = buildPath;

@forgezero/access/testing

Deterministic access-pipeline fixtures and assertions for consumer tests. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  reachableRoutes,
} from '@forgezero/access/testing';

@forgezero/access/testing — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  reachableRoutes,
} from '@forgezero/access/testing';

export const selectedCapability = reachableRoutes;

@forgezero/access/header

Strict configurable header-identity extraction with canonical names and bounded values. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  defineHeaderIdentitySources,
} from '@forgezero/access/header';

@forgezero/access/header — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  defineHeaderIdentitySources,
} from '@forgezero/access/header';

export const selectedCapability = defineHeaderIdentitySources;

@forgezero/access/principal

Generic principal-source resolution for browser, API-key, attestation or future identity adapters. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  assignmentIsActive,
} from '@forgezero/access/principal';

@forgezero/access/principal — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  assignmentIsActive,
} from '@forgezero/access/principal';

export const selectedCapability = assignmentIsActive;

@forgezero/access/principal-session

Short-lived scope-bound delegated-principal sessions with sliding and absolute expiry. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  DEFAULT_PRINCIPAL_ABSOLUTE_TTL_MS,
} from '@forgezero/access/principal-session';

@forgezero/access/principal-session — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  DEFAULT_PRINCIPAL_ABSOLUTE_TTL_MS,
} from '@forgezero/access/principal-session';

export const selectedCapability = DEFAULT_PRINCIPAL_ABSOLUTE_TTL_MS;

@forgezero/access/authenticator

Authentication-source contracts for adding identity mechanisms without changing route policy. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  createAuthenticator,
} from '@forgezero/access/authenticator';

@forgezero/access/authenticator — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  createAuthenticator,
} from '@forgezero/access/authenticator';

export const selectedCapability = createAuthenticator;

@forgezero/access/ceremony-modes

Named security-ceremony modes and their session/action fulfilment semantics. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  MAX_CUSTODIANS,
} from '@forgezero/access/ceremony-modes';

@forgezero/access/ceremony-modes — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  MAX_CUSTODIANS,
} from '@forgezero/access/ceremony-modes';

export const selectedCapability = MAX_CUSTODIANS;

1. Install

Zero runtime dependencies. The core is fetch types plus plain JSON Schema, so it runs on Bun, Node 18+, Cloudflare Workers, Deno and every edge runtime.

bun add @forgezero/access

2. Declare routes and who may reach them

Routes carry their contract — label, method, and the shapes they accept and return. WHO may reach them is a separate list, because the two change for different reasons and on different schedules.

import {
  defineRoutes,
  defineAccessControl,
  page,
  action,
} from '@forgezero/access';

export const ROUTES = defineRoutes({
  orders:                    page('Orders'),
  'api/orders':              action('List', 'GET',  { page: 'orders' }),
  'api/orders/[id]/refund':  action('Refund', 'POST', { page: 'orders' })
});

export const ACCESS = defineAccessControl({
  factors: FACTORS,
  routes: ROUTES,
  sessionPolicies: {
    member: { factors: ['passkey'], routes: ['orders', 'api/orders'] },
    admin:  { factors: ['passkey'], routes: ['api/orders/[id]/refund'] }
  }
});

3. Mount it

One line per runtime. The pipeline is written once and shared, so an adapter never re-decides anything.

// anywhere fetch exists — Workers, Deno, Node, Bun
import {
  toFetch,
} from '@forgezero/access/fetch';
export default { fetch: toFetch({ access: ACCESS, handlers: HANDLERS }) };

// Elysia
import {
  elysia,
} from '@forgezero/access/elysia';
app.use(elysia({ access: ACCESS, handlers: HANDLERS, Elysia }));

Every route needs a session policy, or the build fails

Exactly one policy must cover each route. A route nobody classified is a route whose security nobody decided — and adding a route is precisely when that happens. This is the rule that catches omission rather than typos, and it is why forgetting is not possible rather than merely discouraged.

SESSION_INCOMPLETE: No session policy covers: api/orders/export.
Every route needs exactly one.

Fresh proof for dangerous actions

actionFactorsRequired is a COUNT: 1 is any-one, the list length is all-of, and anything between is M-of-N with no special case. The proof binds to the record your before-handler loaded, so a key minted to refund order A cannot refund order B.

actionPolicies: {
  sensitive: {
    factors: ['passkey', 'telegram', 'totp'],
    required: 2,          // any 2 of the 3
    target: 'orders',
    routes: ['api/orders/[id]/refund']
  }
}

A session factor NEVER satisfies an action factor

fulfilledActionFactors() returns an empty array, always. A five-minute verified-at timestamp looks equivalent and is not: a timestamp IS a persisted factor, so a left-open laptop or a stolen cookie replays the privileged action. Returning nothing makes that impossible by construction rather than by policy.

Disabling a factor tells you what it breaks, first

The effective pool is the route factors intersected with the factors you have enabled. If that falls below the required count the route becomes UNAVAILABLE — never quietly weakened to whatever remains. Ask before saving rather than discovering it during an incident.

impactOfDisabling(ACCESS, ['passkey'])
// [{ route: 'api/orders/[id]/refund', available: 1, required: 2 }]

Test it without a server

simulate() reports which policy decided, which a browser 403 never tells you. reachableRoutes() answers what a role can actually do — worth running, because stem inheritance grants more than a grant list reads like.

import {
  simulate,
  reachableRoutes,
} from '@forgezero/access/testing';

simulate(ACCESS, { route: 'api/settings', roles, as: 'member' });
// { allowed: false, status: 403, reason: 'ACCESS_DENIED', sessionPolicy: 'admin' }

reachableRoutes(ACCESS, roles, ['member']);
// holding 'orders' also grants api/orders/[id]/refund — stems inherit

Conditions: the guards, already written

Every project writes the same dozen checks into its before-handlers. These are those checks, each declaring the status it refuses with. requireOwner answers 404 rather than 403 on purpose — a 403 confirms the record exists, which turns sequential identifiers into an enumeration oracle.

import {
  loadTarget,
  requireOwner,
  requireState,
  requireBalance,
} from '@forgezero/access/conditions';

beforeHandlers: {
  load:    loadTarget({ routes: ['api/orders/[id]/refund'], load: findOrder }),
  mine:    requireOwner({ routes: ['api/orders/[id]/refund'], owner: o => o.userKey }),
  payable: requireState({ routes: ['api/orders/[id]/refund'],
                          status: o => o.status, allowed: ['paid'] })
}

A refusal keeps its own status

A condition throws a Refusal carrying the status the client deserves, so "already refunded" is a 409 the UI can explain rather than a 500 that tells the client to retry. An idempotent replay throws Settled instead and returns the original answer — because a retrying client needs to learn the transfer succeeded, which no error code can tell it.

throw new Refusal(409, 'STATE_INVALID', 'Already refunded.', { status: 'refunded' });

// idempotent replay — the ORIGINAL result, not an error
throw new Settled({ ok: true, id: 'ref_1' }, 201);

Undeclared refusals fail the build

Each condition knows which statuses it can produce, so the set a route can answer is derivable. Add a quota check to a route whose contract never mentions 409 and the build stops — rather than a client rendering "an unexpected error" for the one refusal a user could have acted on.

assertDeclaredRefusals({ routes: ROUTES, conditions: CONDITIONS });
// Undeclared refusals:
//   api/compute/allocate can 409 (requireQuota) but does not declare it

Effects: what happens once it is decided

Audit, emit, meter, invalidate and notify. None can fail the request — a dead audit sink must not turn a completed transfer into a 500. Audit records denials as well as successes, because a run of 403s from one session is the signal an incident is reconstructed from. Every payload is redacted first.

import {
  audit,
  emit,
  meter,
} from '@forgezero/access/effects';

afterHandlers: {
  trail: audit({ routes: [...], sink }),
  event: emit({ routes: [...], outbox, type: 'order.refunded',
                payload: (ctx, result) => ({ id: result.id }) }),
  usage: meter({ routes: [...], meter, unit: 'request' })  // successes only
}

Response codes, and what each means

A 428 is not a rejection: it names the missing proof and the same request succeeds on replay. A 404 for a route outside its stage is deliberate — a 403 would confirm the route exists.

401  no session
403  session is fine, the role lacks this route
404  route exists but not in this stage, realm or feature
409  a condition refused — state, balance, quota or approval
412  the record changed since you read it
422  the request did not match what the route accepts
423  locked — a human must act, unlike 503
428  a factor is missing — headers name which
429  rate limited

Full rendered documentation: https://www.forgezero.net/docs/access