axis-platform-sdk 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,7 +2,22 @@
 
 All notable changes to `axis-platform-sdk`. Pre-release; not yet published to npm.
 
-## [0.2.0] — 2026-06-25 (unreleased)
+## [0.2.1] — 2026-06-25
+
+### Added — TypeScript declarations
+
+- The package now ships `.d.ts` types (it stays authored in plain JS). A
+  complete `src/index.d.ts` covers the full main-entry surface (verify,
+  authorizer, scope, gate, client, ledger, blocklist, reportback); each subpath
+  export (`./scope`, `./gate`, `./authorizer`, `./ledger`, `./blocklist`,
+  `./reportback`) re-exports its slice. `package.json` exposes them via a
+  top-level `types` field and per-subpath `types` conditions in `exports`.
+- This lets TypeScript consumers (e.g. Owyhee "The Door", swapping its vendored
+  copy for the npm dependency) drop their hand-maintained declaration and get
+  types from the package. Verified by a clean-room install + strict `tsc` of a
+  consumer importing from the root and a subpath.
+
+## [0.2.0] — 2026-06-25
 
 First npm publish + public repo. Adds the stateful half (ledger, blocklist,
 reputation report-back) and reconciles it with Owyhee "The Door" (governor#27)

package/README.md

@@ -16,7 +16,7 @@ The registry already does the hard part. `GET /verify?token=<AIT>` checks the si
 npm install axis-platform-sdk
 ```
 
-Zero dependencies. Runs in Node 20+, Cloudflare Workers, and modern browsers.
+Zero dependencies. Runs in Node 20+, Cloudflare Workers, and modern browsers. Ships TypeScript declarations (the package is authored in plain JS).
 
 ## Quickstart — gate a Worker endpoint
 

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "axis-platform-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Platform-side SDK for the AXIS protocol. The verifier/'bouncer' side: when an AXIS agent shows up at your platform, verify its identity + delegation + scope and decide whether to accept, scope, or boot it. Zero runtime dependencies; runs in Node 20+, Cloudflare Workers, and modern browsers.",
   "type": "module",
   "main": "src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./scope": "./src/scope.js",
-    "./gate": "./src/gate.js",
-    "./authorizer": "./src/authorizer.js",
-    "./ledger": "./src/ledger.js",
-    "./blocklist": "./src/blocklist.js",
-    "./reportback": "./src/reportback.js"
+    ".": { "types": "./src/index.d.ts", "default": "./src/index.js" },
+    "./scope": { "types": "./src/scope.d.ts", "default": "./src/scope.js" },
+    "./gate": { "types": "./src/gate.d.ts", "default": "./src/gate.js" },
+    "./authorizer": { "types": "./src/authorizer.d.ts", "default": "./src/authorizer.js" },
+    "./ledger": { "types": "./src/ledger.d.ts", "default": "./src/ledger.js" },
+    "./blocklist": { "types": "./src/blocklist.d.ts", "default": "./src/blocklist.js" },
+    "./reportback": { "types": "./src/reportback.d.ts", "default": "./src/reportback.js" }
   },
   "scripts": {
     "test": "node --test test/scope.test.js test/verify.test.js test/authorizer.test.js test/ledger.test.js test/blocklist.test.js test/reportback.test.js"

package/src/authorizer.d.ts

@@ -0,0 +1 @@
+export { SwitchAuthorizer, SwitchPolicy, GateConfig, AuthorizeContext, Verdict } from './index.js';

package/src/blocklist.d.ts

@@ -0,0 +1,9 @@
+export {
+  Blocklist,
+  MemoryBlocklistStore,
+  gatedWithBlocklist,
+  BlockKind,
+  BlockMeta,
+  BlockEntry,
+  BlocklistStore,
+} from './index.js';

package/src/gate.d.ts

@@ -0,0 +1 @@
+export { aitGate, extractToken, denialResponse, VerifyOptions, Verdict } from './index.js';

package/src/index.d.ts

@@ -0,0 +1,288 @@
+// Type declarations for axis-platform-sdk (the package is authored in plain JS).
+// Covers the full main-entry surface. Subpath entry points (./scope, ./gate,
+// ./authorizer, ./ledger, ./blocklist, ./reportback) re-export their slice of
+// this declaration. Keep in sync with src/*.js.
+
+export type Tier = 'email' | 'domain' | 'verified' | 'kyb_individual' | 'kyb_organization';
+
+// --- verify -----------------------------------------------------------------
+
+/** The single structured verdict verifyAgent / SwitchAuthorizer.authorize return. */
+export interface Verdict {
+  accepted: boolean;
+  code?: string;
+  reason?: string;
+  agent_id?: string;
+  operator_id?: string;
+  effective_scope?: string[];
+  delegation_valid?: boolean;
+  tier?: Tier | null;
+  expires_at?: number | null;
+  /** present on an insufficient_scope denial */
+  missing?: string[];
+}
+
+export interface VerifyOptions {
+  audience?: string;
+  requireScopes?: string[];
+  minTier?: Tier;
+  blockedOperators?: string[];
+  approvedOperators?: string[] | null;
+  registryBaseUrl?: string;
+  fetchImpl?: typeof fetch;
+}
+
+export function verifyAgent(token: string, opts?: VerifyOptions): Promise<Verdict>;
+
+// --- authorizer (the pluggable gate engine; SwitchAuthorizer = free tier) ----
+
+export interface GateConfig {
+  enabled?: boolean;
+  minTier?: Tier;
+  requireScopes?: string[];
+  blockedOperators?: string[];
+  approvedOperators?: string[] | null;
+}
+
+/** Exactly what the "Door policy" screen edits + saves (door_policy.policy_json). */
+export interface SwitchPolicy {
+  audience?: string;
+  defaultAllow?: boolean;
+  blockedOperators?: string[];
+  gates?: Record<string, GateConfig>;
+}
+
+export interface AuthorizeContext {
+  registryBaseUrl?: string;
+  fetchImpl?: typeof fetch;
+}
+
+export class SwitchAuthorizer {
+  constructor(policy?: SwitchPolicy);
+  policy: SwitchPolicy;
+  optsForGate(gateId: string): VerifyOptions;
+  authorize(token: string, gateId: string, ctx?: AuthorizeContext): Promise<Verdict>;
+  gate(gateId: string, opts?: AuthorizeContext): (request: Request) => Promise<Verdict>;
+}
+
+// --- scope ------------------------------------------------------------------
+
+export function scopeCovers(granted: string, required: string): boolean;
+/** Returns { ok, missing } — NOT a boolean. */
+export function coversAll(granted: string[], required: string[]): { ok: boolean; missing: string[] };
+
+// --- gate (Worker request middleware) ---------------------------------------
+
+export function aitGate(opts: VerifyOptions): (request: Request) => Promise<Verdict>;
+export function extractToken(request: Request): string | null;
+export function denialResponse(verdict: Verdict): Response;
+
+// --- client (registry-call helpers) -----------------------------------------
+
+export interface EnrichResult {
+  agent_id: string;
+  did?: string | null;
+  display_name?: string | null;
+  tier?: Tier | null;
+  operator_id?: string;
+  status?: string | null;
+  raw?: unknown;
+  [k: string]: unknown;
+}
+export function enrich(
+  agentId: string,
+  token: string | null,
+  opts?: { registryBaseUrl?: string; fetchImpl?: typeof fetch },
+): Promise<EnrichResult>;
+
+export function registryGet(
+  base: string,
+  path: string,
+  opts?: { headers?: Record<string, string>; fetchImpl?: typeof fetch },
+): Promise<{ status: number; body: any }>;
+
+/** Read an operator's verification tier from a resolved agent record. */
+export function pickTier(agentBody: any): Tier | null;
+
+/** Load a platform's published `/.well-known/axis-access` door policy. */
+export function loadAccessPolicy(
+  platformBaseUrl: string,
+  opts?: { fetchImpl?: typeof fetch },
+): Promise<SwitchPolicy & Record<string, unknown>>;
+
+export function decodeAitPayload(token: string): Record<string, unknown> | null;
+export const TIER_RANK: Record<string, number>;
+export const DEFAULT_REGISTRY: string;
+
+// --- ledger (the "who showed up" arrival record) ----------------------------
+
+export type ArrivalDecision = 'auto_allow' | 'denied' | 'held' | 'approved' | 'booted';
+
+/**
+ * One arrival record. Byte-compatible with Owyhee "The Door"'s `arrivals`
+ * columns / `ArrivalRecord` (minus the adapter's own id/org_id PKs).
+ * `created_at` is epoch ms.
+ */
+export interface ArrivalEntry {
+  agent_id: string | null;
+  operator_id: string | null;
+  created_at: number;
+  tier: Tier | null;
+  delegation_valid: boolean;
+  effective_scope: string[];
+  gate_id: string | null;
+  requested_action: string | null;
+  display_name: string | null;
+  decision: ArrivalDecision;
+  reason: string | null;
+  audience: string | null;
+}
+
+/** Optional fields stamped onto an entry alongside the verdict. */
+export interface RecordFields {
+  audience?: string;
+  gate_id?: string;
+  requested_action?: string;
+  display_name?: string;
+  decision?: ArrivalDecision;
+  created_at?: number;
+}
+
+export function recordEntry(verdict: Verdict, fields?: RecordFields): ArrivalEntry;
+
+/** The pluggable ledger store port (the default is in-memory). */
+export interface LedgerStore {
+  append(entry: ArrivalEntry): Promise<void>;
+  recent(opts?: { limit?: number }): Promise<ArrivalEntry[]>;
+  byOperator(operatorId: string, opts?: { limit?: number }): Promise<ArrivalEntry[]>;
+}
+
+export class MemoryLedgerStore implements LedgerStore {
+  constructor(opts?: { max?: number });
+  append(entry: ArrivalEntry): Promise<void>;
+  recent(opts?: { limit?: number }): Promise<ArrivalEntry[]>;
+  byOperator(operatorId: string, opts?: { limit?: number }): Promise<ArrivalEntry[]>;
+}
+
+export class AccessLedger {
+  constructor(opts?: { store?: LedgerStore });
+  store: LedgerStore;
+  record(verdict: Verdict, fields?: RecordFields): Promise<ArrivalEntry>;
+  recent(opts?: { limit?: number }): Promise<ArrivalEntry[]>;
+  byOperator(operatorId: string, opts?: { limit?: number }): Promise<ArrivalEntry[]>;
+}
+
+export function loggedGate(
+  gate: (request: Request) => Promise<Verdict>,
+  ledger: AccessLedger,
+  fields?: RecordFields,
+): (request: Request) => Promise<Verdict>;
+
+// --- blocklist (runtime block/allow, by operator AND agent) -----------------
+
+export type BlockKind = 'operator' | 'agent';
+export interface BlockMeta { reason?: string; created_at?: number; [k: string]: unknown; }
+export interface BlockEntry { id: string; meta: BlockMeta; }
+
+/** The pluggable block-store port (the default is in-memory). */
+export interface BlocklistStore {
+  add(kind: BlockKind, id: string, meta?: BlockMeta): Promise<void>;
+  remove(kind: BlockKind, id: string): Promise<void>;
+  has(kind: BlockKind, id: string): Promise<boolean>;
+  list(kind: BlockKind): Promise<BlockEntry[]>;
+}
+
+export class MemoryBlocklistStore implements BlocklistStore {
+  add(kind: BlockKind, id: string, meta?: BlockMeta): Promise<void>;
+  remove(kind: BlockKind, id: string): Promise<void>;
+  has(kind: BlockKind, id: string): Promise<boolean>;
+  list(kind: BlockKind): Promise<BlockEntry[]>;
+}
+
+export class Blocklist {
+  constructor(opts?: { store?: BlocklistStore });
+  store: BlocklistStore;
+  blockOperator(operatorId: string, reason?: string): Promise<void>;
+  blockAgent(agentId: string, reason?: string): Promise<void>;
+  unblockOperator(operatorId: string): Promise<void>;
+  unblockAgent(agentId: string): Promise<void>;
+  isOperatorBlocked(operatorId: string): Promise<boolean>;
+  isAgentBlocked(agentId: string): Promise<boolean>;
+  blockedOperatorIds(): Promise<string[]>;
+  listOperators(): Promise<BlockEntry[]>;
+  listAgents(): Promise<BlockEntry[]>;
+  verifyOpts(): Promise<{ blockedOperators: string[] }>;
+  checkVerdict(verdict: Verdict): Promise<Verdict>;
+}
+
+export function gatedWithBlocklist(
+  gate: (request: Request) => Promise<Verdict>,
+  blocklist: Blocklist,
+): (request: Request) => Promise<Verdict>;
+
+// --- reportback (sign + emit a negative Trust Attestation) ------------------
+
+export interface TrustAttestation {
+  axis_version: string;
+  type: 'TrustAttestation';
+  id: string;
+  issued_by: string;
+  subject: string;
+  issued_at: string;
+  scope: string;
+  statement: string;
+  signature?: string;
+}
+
+export interface KeyStore {
+  load(): Promise<JsonWebKey | null>;
+  save(jwk: JsonWebKey): Promise<void>;
+}
+
+export class MemoryKeyStore implements KeyStore {
+  load(): Promise<JsonWebKey | null>;
+  save(jwk: JsonWebKey): Promise<void>;
+}
+
+export function getPlatformKey(
+  opts?: { keyStore?: KeyStore },
+): Promise<{ privateKey: CryptoKey; publicKeyB64: string; jwk: JsonWebKey }>;
+
+export function buildAttestation(args: {
+  platformId: string;
+  agentId: string;
+  category?: string;
+  reason?: string;
+  issuedAt?: string;
+}): TrustAttestation;
+
+export function signAttestation(attestation: TrustAttestation, privateKey: CryptoKey): Promise<TrustAttestation>;
+export function verifyAttestation(attestation: TrustAttestation, publicKeyB64: string): Promise<boolean>;
+
+export interface ReportArgs {
+  platformId: string;
+  agentId: string;
+  operatorId?: string;
+  category: string;
+  reason: string;
+}
+export interface ReportResult {
+  sent: boolean;
+  status?: number;
+  attestation?: TrustAttestation;
+  reason?: string;
+}
+export interface ReportOptions {
+  reputationUrl?: string | null;
+  keyStore?: KeyStore;
+  fetchImpl?: typeof fetch;
+}
+
+export function reportFlag(args: ReportArgs, opts?: ReportOptions): Promise<ReportResult>;
+export function blockAndReport(
+  blocklist: Blocklist,
+  args: ReportArgs,
+  opts?: ReportOptions,
+): Promise<{ blocked: boolean; agent_id: string; report: ReportResult }>;
+
+export const DEFAULT_REPUTATION_URL: string | null;

package/src/ledger.d.ts

@@ -0,0 +1,10 @@
+export {
+  AccessLedger,
+  MemoryLedgerStore,
+  loggedGate,
+  recordEntry,
+  ArrivalEntry,
+  ArrivalDecision,
+  RecordFields,
+  LedgerStore,
+} from './index.js';

package/src/reportback.d.ts

@@ -0,0 +1,15 @@
+export {
+  reportFlag,
+  blockAndReport,
+  getPlatformKey,
+  buildAttestation,
+  signAttestation,
+  verifyAttestation,
+  MemoryKeyStore,
+  TrustAttestation,
+  KeyStore,
+  ReportArgs,
+  ReportResult,
+  ReportOptions,
+  DEFAULT_REPUTATION_URL,
+} from './index.js';

package/src/scope.d.ts

@@ -0,0 +1 @@
+export { scopeCovers, coversAll } from './index.js';