ankr-trust-constants

32-bit bitmask constants for the AnkrForja trust protocol.

One integer encodes the full permission surface of any service in the ANKR universe. Import the constants. Never hardcode magic numbers.

npm install ankr-trust-constants

---

Why Bitmask Over String Arrays

String arrays require parsing, matching, and interpretation. At 200+ services, interpretation is hallucination.

// String array — requires parsing, order-sensitive, typo-prone
if (user.roles.includes('BOOKING_CREATE')) { ... }

// Bitmask — one CPU instruction, binary truth
if (hasPerm(trust_mask, BOOK)) { ... }

hasPerm(mask, BOOK) is (mask & BOOK) !== 0. Either the bit is set or it isn't. No string matching. No interpretation. No hallucination possible.

At 200 services, a Codex query runs (mask & BOOK) !== 0 across 200 rows in one pass. Sub-millisecond. Zero ambiguity.

---

Install

npm install ankr-trust-constants

---

The 32-bit Allocation

The allocation is globally owned by the ANKR platform and is append-only. Once a bit position is assigned a meaning, it cannot be reassigned. Retired bits are set to 0 — never reused.

Bits 0–7 — Universal Forja (cross-service)

These bits apply across all services in the ANKR universe.

Bit	Name	Hex	Description
0	READ	0x00000001	Read any resource — list, get
1	QUERY	0x00000002	Query structured data — search, filter
2	WRITE	0x00000004	Create or update — reversible write
3	EXECUTE	0x00000008	Execute an action — may have side effects
4	APPROVE	0x00000010	Approve a pending action or document
5	AUDIT	0x00000020	Access audit logs and compliance records
6	ADMIN	0x00000040	Administrative operations — user management, config
7	SUPER	0x00000080	Universal override — requires explicit human approval to grant

Bits 8–15 — Maritime 8x Block

Applies in: Liner8x, Feeder8x, MPV8x, Mari8x, AnkreBL, MariBFC, AnkrGrid Maritime.

Bit	Name	Hex	Description
8	BOOK	0x00000100	Create bookings
9	MANIFEST	0x00000200	Close and manage cargo manifests
10	BL_ISSUE	0x00000400	Issue electronic Bills of Lading
11	RATE_DESK	0x00000800	Set and approve freight rates
12	FEEDER_OPS	0x00001000	Feeder vessel operations — rotation, allocation
13	NETWORK_PLAN	0x00002000	Network planning and service design
14	VESSEL_OPS	0x00004000	Vessel operations — maintenance, port calls
15	COMPLIANCE_OVERRIDE	0x00008000	Override compliance flags — highest-risk, requires AUDIT bit

Bits 16–23 — Logistics Block

Applies in: Por8x, PortWatch, TradeMitra, FreightBox, WowTruck.

Bit	Name	Hex	Description
16	GATE_IN	0x00010000	Authorise container/cargo gate-in
17	TRACK	0x00020000	Track shipments and containers
18	FTA_CHECK	0x00040000	Run FTA eligibility and duty optimisation
19	ALERT_ACK	0x00080000	Acknowledge operational alerts
20	PORT_OPS	0x00100000	Port operational management
21–23	(reserved)	—	Allocated by platform team when needed

Bits 24–31 — AGI Autonomy Tier

Maps 1:1 to AnkrClaw action-gate tiers. Applies to AI agents — evaluated as a ceiling, not a floor. An agent without AI_EXECUTE cannot execute actions even if it has WRITE.

Bit	Name	Hex	Description
24	AI_READ	0x01000000	Agent can observe state and retrieve data
25	AI_QUERY	0x02000000	Agent can run structured queries
26	AI_SUGGEST	0x04000000	Agent can propose actions — human approves
27	AI_EXECUTE	0x08000000	Agent can execute low-risk actions autonomously
28	AI_APPROVE	0x10000000	Agent can approve pending operations
29	AUTONOMOUS	0x20000000	Council synthesis required before any execution
30–31	(reserved)	—	Allocated by platform team when needed

---

Helper Functions

hasPerm(mask, perm)

Returns true if the single permission bit is set in the mask.

import { hasPerm, BOOK, BL_ISSUE } from 'ankr-trust-constants'

const mask = 0x00000507  // READ + QUERY + WRITE + EXECUTE + BOOK

hasPerm(mask, BOOK)     // true
hasPerm(mask, BL_ISSUE) // false

hasAllPerms(mask, ...perms)

Returns true only if all listed permission bits are set.

import { hasAllPerms, MANIFEST, BL_ISSUE, AUDIT } from 'ankr-trust-constants'

// Can this principal issue a BL? Needs MANIFEST + BL_ISSUE + AUDIT trail
if (hasAllPerms(mask, MANIFEST, BL_ISSUE, AUDIT)) {
  await issueBillOfLading(shipment)
}

hasAnyPerm(mask, ...perms)

Returns true if at least one of the listed permission bits is set.

import { hasAnyPerm, ADMIN, SUPER } from 'ankr-trust-constants'

if (hasAnyPerm(mask, ADMIN, SUPER)) {
  showAdminPanel()
}

describePerms(mask)

Returns a human-readable array of permission names for logging and audit trails.

import { describePerms } from 'ankr-trust-constants'

describePerms(0x00000307)
// ['READ', 'QUERY', 'WRITE', 'EXECUTE', 'BOOK', 'MANIFEST']

// Use in audit logs — never for permission evaluation
console.log(`Agent granted: ${describePerms(trust_mask).join(', ')}`)

---

Role Presets

Pre-composed masks for common roles. Build your own by ORing constants together.

ROLE_MASK — Universal roles

import { ROLE_MASK } from 'ankr-trust-constants'

ROLE_MASK.GUEST       // 0x00000001  READ only
ROLE_MASK.VIEWER      // 0x00000003  READ + QUERY
ROLE_MASK.OPERATOR    // 0x0000000F  READ + QUERY + WRITE + EXECUTE
ROLE_MASK.APPROVER    // 0x0000001F  OPERATOR + APPROVE
ROLE_MASK.AUDITOR     // 0x00000023  READ + QUERY + AUDIT
ROLE_MASK.ADMIN       // 0x0000007F  All universal bits except SUPER
ROLE_MASK.SUPER_ADMIN // 0x000000FF  All universal bits including SUPER

MARITIME_ROLE_MASK — Maritime 8x roles

import { MARITIME_ROLE_MASK } from 'ankr-trust-constants'

// Shipper — can create bookings, read status
MARITIME_ROLE_MASK.SHIPPER
// 0x00000107  READ + QUERY + WRITE + BOOK

// Liner Operations — full maritime surface, no AGI bits
MARITIME_ROLE_MASK.LINER_OPS
// 0x0000FF07  All universal (no SUPER) + all maritime bits

// AI Agent (read-only tier)
MARITIME_ROLE_MASK.AI_READ_ONLY
// 0x03000003  READ + QUERY + AI_READ + AI_QUERY

// AI Agent (execution tier)
MARITIME_ROLE_MASK.AI_EXECUTE
// 0x0F000007  READ + QUERY + WRITE + AI_READ + AI_QUERY + AI_SUGGEST + AI_EXECUTE

Composing custom masks

import { READ, QUERY, BOOK, MANIFEST, AI_READ, AI_QUERY } from 'ankr-trust-constants'

// A read-only AI agent that can also query bookings
const agentMask = READ | QUERY | BOOK | AI_READ | AI_QUERY
// 0x03000103

---

Full Usage Example (with AnkrForja)

import Fastify from 'fastify'
import { codexAgent } from 'ankr-forja'
import { hasPerm, hasAllPerms, WRITE, BOOK, MANIFEST, BL_ISSUE, AI_EXECUTE } from 'ankr-trust-constants'

const app = Fastify()
await codexAgent(app, { codexPath: './codex.json' })

app.post('/api/bookings', async (req, reply) => {
  const trust = await fetch(`/api/v2/forja/trust`).then(r => r.json())
  const mask: number = trust.trust_mask

  // Check: can this principal create a booking?
  if (!hasAllPerms(mask, WRITE, BOOK)) {
    return reply.code(403).send({ error: 'Insufficient permissions: WRITE + BOOK required' })
  }

  // Check: is this an AI agent trying to execute?
  const isAiAgent = req.headers['x-agent-id'] !== undefined
  if (isAiAgent && !hasPerm(mask, AI_EXECUTE)) {
    return reply.code(403).send({ error: 'FRJ-011: AI_EXECUTE bit required for autonomous booking' })
  }

  return reply.code(201).send({ booking_id: 'BK-2026-001' })
})

await app.listen({ port: 4000 })

---

Rules

• BMK-003 Bit allocation is append-only. Once assigned, a bit position cannot be reassigned.
• BMK-004 Import from ankr-trust-constants only. Never hardcode magic numbers for bit positions.
• BMK-006 The mask is authoritative. String role arrays are informational only.
• BMK-YK-004 For AI agents, check bits 24–31 before evaluating domain bits. The AGI tier is a ceiling.
• BMK-YK-007 hasPerm takes a single bit. Passing a multi-bit mask to required_perm means "any of these" — use hasAllPerms for "all of these".
• BMK-YK-009 trust_mask: 0 for a non-guest principal is a misconfiguration. Log a warning, fall back to string role evaluation.

---

Append-Only Guarantee

This package's bit assignments are permanent. The CHANGELOG will only ever add new bit assignments — never change or remove existing ones. Consumers can safely depend on any exported constant remaining stable across all future versions.

---

License

Apache 2.0 — open protocol. Anyone implements it.

---

Built by ANKR Labs | PowerPbox IT Solutions Pvt Ltd Capt. Anil Kumar Sharma — capt.anil.sharma@powerpbox.org