Security and access

Share validated contracts between your API and frontend, then add access and action policies.

Install

Typed route, principal, factor, RBAC and request-pipeline contracts. 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.

bun add @forgezero/access

Share one validated contract between API and frontend

Put routes in your application’s shared module. The server validates requests and successful responses; the frontend infers arguments and results from those same routes. Add your session and action policies before exposing protected data. This public example needs no framework or database.

import {
  action,
  defineRoutes,
  defineAccessControl,
  defineFactors,
} from '@forgezero/access';
import {
  schema,
} from '@forgezero/access/schema';
import {
  defineHandlers,
} from '@forgezero/access/pipeline';
import {
  toFetch,
} from '@forgezero/access/fetch';
import {
  createClient,
} from '@forgezero/access/client';

// Shared contract. Both applications import this value.
const routes = defineRoutes({
  'api/hello': action('Say hello', 'POST', {
    body: schema.object({ name: schema.string({ minLength: 1, maxLength: 80 }) }),
    response: { 200: schema.object({ greeting: schema.string() }) }
  })
});

// API. Mount serve in any Fetch-compatible server.
const access = defineAccessControl({ routes, factors: defineFactors({}),
  sessionPolicies: { public: { factors: [], routes: ['api/hello'] } } });
const serve = toFetch({ access, handlers: defineHandlers(routes, {
  'api/hello': context => ({ greeting: 'Hello, ' + context.body.name })
}) });

// Frontend. The injected transport makes this example runnable without a host.
// For your deployed API, omit fetch and use its real baseUrl.
const client = createClient(routes, { baseUrl: 'https://api.example.test',
  fetch: ((input, init) => serve(new Request(input, init))) as typeof fetch });
const result = await client['api/hello']({ body: { name: 'Ada' } });
if (result.ok) console.log(result.data.greeting);
else console.error(result.error.message);

Declare an exact Vault domain and deployment binding

Service records, platform authority, and deployment inputs are distinct runtime-validated coordinates. Deployment credentials always name their exact deployment and environment.

import {
  parse,
} from '@forgezero/access/schema';
import {
  DeploymentVaultCoordinateV3Schema,
} from '@forgezero/access/vault';

const coordinate = parse(DeploymentVaultCoordinateV3Schema, {
  realmId: 'tenant-a',
  deploymentKey: 'api',
  environmentKey: 'development',
  entryKey: 'DATABASE_URL'
});
if (!coordinate.ok) throw new Error('Invalid deployment Vault coordinate');

Choose an entry point

Import the capability your application needs. Each package ships TypeScript declarations. Backend-only entries must stay out of browser bundles.

| Import or command | Use it for | Runtime | |---|---|---| | @forgezero/access | Declare routes, factors and policies as orthogonal lists; authorise against them. | Portable | | @forgezero/access/schema | Dependency-free JSON Schema builders, inference, Pick/Omit/Extend composition and runtime boundary parsing so request and response types have one source. | Portable | | @forgezero/access/conditions | The twelve guards every project writes into before, each with the status its refusal deserves. | Portable | | @forgezero/access/effects | Audit, emit, meter, invalidate and notify — what happens after a request is decided, never failing it. | Portable | | @forgezero/access/security | Constant-time comparison, CSPRNG tokens, HMAC, HKDF, AES-GCM sealing and redaction. Web Crypto only. | Portable | | @forgezero/access/rate-limit | Request counters over a window — in memory, in Redis, or in a Durable Object. | Portable | | @forgezero/access/fetch | A Fetch-native adapter over the declared access pipeline. | Portable | | @forgezero/access/pipeline | The framework-neutral route, principal, factor, policy, rate-limit and effects pipeline. | Portable | | @forgezero/access/elysia | Elysia integration over the same access pipeline and route declarations. | Portable | | @forgezero/access/client | Inferred route arguments/results, executable request and response validation, and exact-request security fulfillment. | Portable | | @forgezero/access/testing | Deterministic access-pipeline fixtures and assertions for consumer tests. | Portable | | @forgezero/access/header | Strict configurable header-identity extraction with canonical names and bounded values. | Portable | | @forgezero/access/principal | Generic principal-source resolution for browser, API-key, attestation or future identity adapters. | Portable | | @forgezero/access/principal-session | Short-lived scope-bound delegated-principal sessions with sliding and absolute expiry. | Portable | | @forgezero/access/authenticator | Authentication-source contracts for adding identity mechanisms without changing route policy. | Portable | | @forgezero/access/ceremony-modes | Named security-ceremony modes and their session/action fulfilment semantics. | Portable | | @forgezero/access/vault | Runtime-validated Service, Platform Authority and exact Deployment Vault coordinates and bindings. | Portable | | @forgezero/access/deployment-agent-claim | Exact Realm/Deployment release-claim wire protocol, including ephemeral repository capability and opaque version-pinned Deployment Vault bindings. | Portable |

Related packages

Add only the packages needed by your application.

| Package | Purpose | Guide | |---|---|---| | @forgezero/vault | Exact Deployment binding reads through a managed Agent or signed API credential. | Read guide | | @forgezero/providers | Typed external providers with priority, health and classified fallback. | Read guide | | @forgezero/runtime | Portable runtime primitives for queries, jobs, events, schemas and finance. | Read guide | | @forgezero/agent | Operator CLI and managed-node agent for bootstrap, deploy and lifecycle. | Read guide |

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