npm.io
1.0.3 • Published yesterday

@x12i/authix-types

Licence
—
Version
1.0.3
Deps
1
Size
70 kB
Vulns
0
Weekly
0

@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. See the root README for the full system overview.


Install

npm install @x12i/authix-types

From the monorepo:

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
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
interface AuthixTokenScope {
  organizationIds?: string[];
  accountIds?: string[];
  workspaceIds?: string[];
  domainIds?: string[];
  projectIds?: string[];
  custom?: Record<string, unknown>;
}
Features
interface AuthixTokenFeature {
  featureId: string;
  enabled: boolean;
  limit?: number;
  metadata?: Record<string, unknown>;
}
App descriptor

Public app metadata (secret is not included):

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
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:

import {
  authixTokenPayloadJsonSchema,
  authixOpenApiComponentSchemas,
} from "@x12i/authix-types/json-schema";

authixOpenApiComponentSchemas bundles schemas used by @x12i/authix-openapi.


Dependencies


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

# 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/schemas.ts, src/json-schema.ts.