# @x12i/authix-types

> Shared TypeScript contracts and Zod schemas for Authix Token Infrastructure

Latest version **1.0.3** (published 2026-11-18) · 0 weekly downloads

## Install

```sh
npm install @x12i/authix-types
pnpm add @x12i/authix-types
yarn add @x12i/authix-types
bun add @x12i/authix-types
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2026-11-18 |
| First published | 2026-05-28 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 69.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |

## Links

- npm: https://www.npmjs.com/package/@x12i/authix-types
- Repository: https://github.com/x12i/authix
- Homepage: https://github.com/x12i/authix/tree/main/packages/token-types#readme
- Issues: https://github.com/x12i/authix/issues
- npm.io page: https://npm.io/package/@x12i/authix-types

## Dependencies (1)

- [zod](https://npm.io/package/zod.md) ^4.6.7

## Recent versions

- 1.0.3 (latest) — 2026-11-18
- 1.0.2 — 2026-05-28
- 1.0.1 — 2026-05-28

## README

# @x12i/authix-types

Shared **TypeScript contracts** and **Zod validation schemas** for Authix Token Infrastructure.

This is the foundation layer: every other package imports types and schemas from here. It has no runtime business logic beyond validation.

Part of the [Authix monorepo](https://github.com/x12i/authix). See the [root README](../../README.md) for the full system overview.

---

## Install

```bash
npm install @x12i/authix-types
```

From the monorepo:

```bash
npm run build -w @x12i/authix-types
npm test -w @x12i/authix-types
```

---

## Exports

| Import path | Contents |
| --- | --- |
| `@x12i/authix-types` | TypeScript interfaces + Zod schemas |
| `@x12i/authix-types/json-schema` | JSON Schema objects derived from Zod (for OpenAPI, docs, codegen) |

---

## Core types

### Identity & subject

```typescript
type AuthixIdentityType =
  | "user"
  | "account"
  | "organization"
  | "service"
  | "agent";

interface AuthixTokenSubject {
  identityId: string;
  identityType: AuthixIdentityType;
  displayName?: string;
  email?: string;
}
```

### Token payload

The decoded contents of an Authix token (`AuthixTokenPayload`):

| Field | Description |
| --- | --- |
| `tokenId` | Unique token identifier |
| `appId` | Issuing application |
| `subject` | Who the token represents |
| `scope?` | Org/account/workspace/domain/project IDs + custom bag |
| `features?` | Feature flags with optional limits |
| `issuedAt` | ISO 8601 datetime |
| `expiresAt?` | ISO 8601 datetime |
| `issuer` | Token issuer string (default `authix`) |
| `audience?` | Intended audiences |
| `metadata?` | Arbitrary key/value |
| `keyVersion?` | Signing key version |

### Scope

```typescript
interface AuthixTokenScope {
  organizationIds?: string[];
  accountIds?: string[];
  workspaceIds?: string[];
  domainIds?: string[];
  projectIds?: string[];
  custom?: Record<string, unknown>;
}
```

### Features

```typescript
interface AuthixTokenFeature {
  featureId: string;
  enabled: boolean;
  limit?: number;
  metadata?: Record<string, unknown>;
}
```

### App descriptor

Public app metadata (secret is **not** included):

```typescript
interface AuthixAppDescriptor {
  appId: string;
  catalogId?: string;
  title: string;
  description?: string;
  secretKeyRef: string;       // e.g. "secret/my-app"
  allowedScopes?: string[];
  allowedFeatures?: string[];
  status: "active" | "disabled";
  createdAt: string;
  updatedAt: string;
}
```

### API request/response types

| Type | Used for |
| --- | --- |
| `AuthixAppCreateRequest` / `AuthixAppCreateResponse` | Register app (`appSecretKey` only on create response) |
| `AuthixTokenIssueRequest` / `AuthixTokenIssueResponse` | Issue tokens |
| `AuthixTokenVerifyRequest` / `AuthixTokenVerifyResponse` | Verify tokens |
| `AuthixTokenDecryptRequest` | Decrypt encrypted tokens |
| `AuthixTokenIntrospectResponse` | Introspection result |
| `AuthixTokenRevokeRequest` | Revoke by tokenId, appId, or identityId |
| `AuthixAuditEvent` | Audit log entries |
| `AuthixApiError` | Standard API error shape |

---

## Zod schemas

All request bodies on the HTTP service are validated with these schemas:

| Schema | Validates |
| --- | --- |
| `authixTokenSubjectSchema` | Token subject |
| `authixTokenScopeSchema` | Scope object |
| `authixTokenFeatureSchema` | Single feature |
| `authixTokenPayloadSchema` | Full payload |
| `authixAppDescriptorSchema` | App record |
| `authixTokenDescriptorSchema` | Stored token metadata |
| `authixTokenIssueRequestSchema` | `POST /v1/tokens/issue` |
| `authixTokenVerifyRequestSchema` | Verify / decrypt / introspect body |
| `authixTokenRevokeRequestSchema` | Revoke body (requires at least one of tokenId, appId, identityId) |
| `authixAppCreateRequestSchema` | `POST /v1/apps` (`appId` must match `^[a-z0-9][a-z0-9-_]*$`) |
| `authixAppUpdateRequestSchema` | `PATCH /v1/apps/:appId` |

### Example: validate at a boundary

```typescript
import {
  authixTokenIssueRequestSchema,
  type AuthixTokenIssueRequest,
} from "@x12i/authix-types";

const body = authixTokenIssueRequestSchema.parse(rawBody);
// body is typed as AuthixTokenIssueRequest
```

---

## JSON Schema export

For OpenAPI components, documentation generators, or JSON Schema tooling:

```typescript
import {
  authixTokenPayloadJsonSchema,
  authixOpenApiComponentSchemas,
} from "@x12i/authix-types/json-schema";
```

`authixOpenApiComponentSchemas` bundles schemas used by `@x12i/authix-openapi`.

---

## Dependencies

- [Zod](https://zod.dev/) — runtime validation
- [zod-to-json-schema](https://github.com/StefanTerdell/zod-to-json-schema) — JSON Schema generation

---

## Related packages

| Package | Relationship |
| --- | --- |
| `@x12i/authix-core` | Uses payload types for create/verify |
| `@x12i/authix-store` | Persists descriptors and audit events |
| `@x12i/authix-service` | Validates HTTP bodies with Zod schemas |
| `@x12i/authix-openapi` | Embeds JSON Schema in OpenAPI spec |

---

## Development

```bash
# From repo root
npm run build -w @x12i/authix-types
npm test -w @x12i/authix-types
npm run typecheck -w @x12i/authix-types
```

Source: [`src/types.ts`](src/types.ts), [`src/schemas.ts`](src/schemas.ts), [`src/json-schema.ts`](src/json-schema.ts).

---
_Source: https://npm.io/package/@x12i/authix-types · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
