@x12i/authx-token-types

Shared TypeScript contracts and Zod validation schemas for AuthX 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 AuthX monorepo. See the root README for the full system overview.

Install

npm install @x12i/authx-token-types

From the monorepo:

npm run build -w @x12i/authx-token-types
npm test -w @x12i/authx-token-types

Exports

| Import path | Contents | | --- | --- | | @x12i/authx-token-types | TypeScript interfaces + Zod schemas | | @x12i/authx-token-types/json-schema | JSON Schema objects derived from Zod (for OpenAPI, docs, codegen) |

Core types

Identity & subject

type AuthxIdentityType =
  | "user"
  | "account"
  | "organization"
  | "service"
  | "agent";

interface AuthxTokenSubject {
  identityId: string;
  identityType: AuthxIdentityType;
  displayName?: string;
  email?: string;
}

Token payload

The decoded contents of an AuthX token (AuthxTokenPayload):

| 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 authx) | | audience? | Intended audiences | | metadata? | Arbitrary key/value | | keyVersion? | Signing key version |

Scope

interface AuthxTokenScope {
  organizationIds?: string[];
  accountIds?: string[];
  workspaceIds?: string[];
  domainIds?: string[];
  projectIds?: string[];
  custom?: Record<string, unknown>;
}

Features

interface AuthxTokenFeature {
  featureId: string;
  enabled: boolean;
  limit?: number;
  metadata?: Record<string, unknown>;
}

App descriptor

Public app metadata (secret is not included):

interface AuthxAppDescriptor {
  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 | | --- | --- | | AuthxAppCreateRequest / AuthxAppCreateResponse | Register app (appSecretKey only on create response) | | AuthxTokenIssueRequest / AuthxTokenIssueResponse | Issue tokens | | AuthxTokenVerifyRequest / AuthxTokenVerifyResponse | Verify tokens | | AuthxTokenDecryptRequest | Decrypt encrypted tokens | | AuthxTokenIntrospectResponse | Introspection result | | AuthxTokenRevokeRequest | Revoke by tokenId, appId, or identityId | | AuthxAuditEvent | Audit log entries | | AuthxApiError | Standard API error shape |

Zod schemas

All request bodies on the HTTP service are validated with these schemas:

| Schema | Validates | | --- | --- | | authxTokenSubjectSchema | Token subject | | authxTokenScopeSchema | Scope object | | authxTokenFeatureSchema | Single feature | | authxTokenPayloadSchema | Full payload | | authxAppDescriptorSchema | App record | | authxTokenDescriptorSchema | Stored token metadata | | authxTokenIssueRequestSchema | POST /v1/tokens/issue | | authxTokenVerifyRequestSchema | Verify / decrypt / introspect body | | authxTokenRevokeRequestSchema | Revoke body (requires at least one of tokenId, appId, identityId) | | authxAppCreateRequestSchema | POST /v1/apps (appId must match ^[a-z0-9][a-z0-9-_]*$) | | authxAppUpdateRequestSchema | PATCH /v1/apps/:appId |

Example: validate at a boundary

import {
  authxTokenIssueRequestSchema,
  type AuthxTokenIssueRequest,
} from "@x12i/authx-token-types";

const body = authxTokenIssueRequestSchema.parse(rawBody);
// body is typed as AuthxTokenIssueRequest

JSON Schema export

For OpenAPI components, documentation generators, or JSON Schema tooling:

import {
  authxTokenPayloadJsonSchema,
  authxOpenApiComponentSchemas,
} from "@x12i/authx-token-types/json-schema";

authxOpenApiComponentSchemas bundles schemas used by @x12i/authx-token-openapi.

Dependencies

• Zod — runtime validation
• zod-to-json-schema — JSON Schema generation

Related packages

| Package | Relationship | | --- | --- | | @x12i/authx-token-core | Uses payload types for create/verify | | @x12i/authx-token-store | Persists descriptors and audit events | | @x12i/authx-token-service | Validates HTTP bodies with Zod schemas | | @x12i/authx-token-openapi | Embeds JSON Schema in OpenAPI spec |

Development

# From repo root
npm run build -w @x12i/authx-token-types
npm test -w @x12i/authx-token-types
npm run typecheck -w @x12i/authx-token-types

Source: src/types.ts, src/schemas.ts, src/json-schema.ts.