@xyo-network/xns-record-payload-plugins 3.0.4 → 3.0.6

package/src/DNS/Witness/Payload/Request.ts

@@ -0,0 +1,40 @@
+import type { PayloadWithSources } from '@xyo-network/payload-model'
+import {
+  isPayloadOfSchemaType,
+  isPayloadOfSchemaTypeWithMeta,
+  isPayloadOfSchemaTypeWithSources,
+} from '@xyo-network/payload-model'
+
+import type { DNSRequestFields, DNSResourceRecordTypeValue } from '../../types/index.ts'
+import { DNSResourceRecordTypes, getRequestFor } from '../../types/index.ts'
+import { DNSSchema } from '../Schema.ts'
+
+/**
+ * The fields of a DNSRequest payload
+ */
+export type DNSRequest = PayloadWithSources<DNSRequestFields, DNSSchema>
+
+/**
+ * Identity function for determining if an object is a DNSRequest payload
+ */
+export const isDNSRequest = isPayloadOfSchemaType<DNSRequest>(DNSSchema)
+
+/**
+ * Identity function for determining if an object is a DNSRequest payload with sources
+ */
+export const isDNSRequestWithSources = isPayloadOfSchemaTypeWithSources<DNSRequest>(DNSSchema)
+
+/**
+ * Identity function for determining if an object is a DNSRequest payload with meta
+ */
+export const isDNSRequestWithMeta = isPayloadOfSchemaTypeWithMeta<DNSRequest>(DNSSchema)
+
+/**
+ * Helper for generating a DNSRequest payload for a given domain and record type
+ * @param domain The domain to query
+ * @param type The record type to query
+ * @returns A DNSRequest payload
+ */
+export const getDnsRequestFor = (domain: string, type: DNSResourceRecordTypeValue = DNSResourceRecordTypes.A): DNSRequest => {
+  return { ...getRequestFor(domain, type), schema: DNSSchema }
+}

package/src/DNS/Witness/Payload/Response.ts

@@ -0,0 +1,29 @@
+import type { PayloadWithSources } from '@xyo-network/payload-model'
+import {
+  isPayloadOfSchemaType,
+  isPayloadOfSchemaTypeWithMeta,
+  isPayloadOfSchemaTypeWithSources,
+} from '@xyo-network/payload-model'
+
+import type { DNSResponseFields } from '../../types/index.ts'
+import { DNSSchema } from '../Schema.ts'
+
+/**
+ * The fields of a DNSResponse payload
+ */
+export type DNSResponse = PayloadWithSources<DNSResponseFields, DNSSchema>
+
+/**
+ * Identity function for determining if an object is a DNSResponse payload
+ */
+export const isDNSResponse = isPayloadOfSchemaType<DNSResponse>(DNSSchema)
+
+/**
+ * Identity function for determining if an object is a DNSResponse payload with sources
+ */
+export const isDNSResponseWithSources = isPayloadOfSchemaTypeWithSources<DNSResponse>(DNSSchema)
+
+/**
+ * Identity function for determining if an object is a DNSResponse payload with meta
+ */
+export const isDNSResponseWithMeta = isPayloadOfSchemaTypeWithMeta<DNSResponse>(DNSSchema)

package/src/DNS/Witness/Payload/index.ts

@@ -0,0 +1,3 @@
+export * from './Payload.ts'
+export * from './Request.ts'
+export * from './Response.ts'

package/src/DNS/Witness/Schema.ts

@@ -0,0 +1,2 @@
+export type DNSSchema = 'network.xyo.dns'
+export const DNSSchema: DNSSchema = 'network.xyo.dns'

package/src/DNS/Witness/index.ts

@@ -0,0 +1,4 @@
+export * from './Config.ts'
+export * from './Params.ts'
+export * from './Payload/index.ts'
+export * from './Schema.ts'

package/src/DNS/index.ts

@@ -0,0 +1,2 @@
+export * from './types/index.ts'
+export * from './Witness/index.ts'

package/src/DNS/types/Answer.ts

@@ -0,0 +1,5 @@
+import type { DNSRecord } from './Record.ts'
+
+export interface DNSAnswer extends DNSRecord {
+  class?: number // The class (typically 1 for IN - Internet)
+}

package/src/DNS/types/Header.ts

@@ -0,0 +1,95 @@
+/* eslint-disable @typescript-eslint/member-ordering */
+
+// An attempt to match compatibility with the RFC 8427 (Representing DNS Messages in JSON)
+// https://www.rfc-editor.org/rfc/rfc8427
+// and Google/CloudFlare's DNS over HTTPS (DoH) standard
+// https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json/
+
+import { type DNSQueryOpcode, DNSQueryOpcodes } from './OperationCodes.ts'
+import type { DNSRcode } from './ResponseCodes.ts'
+import { DNSRcodes } from './ResponseCodes.ts'
+
+// NOTE: The RFC says `Boolean` but uses 0/1 for the values. DNS over HTTPS (DoH) uses `true`/`false`.
+export type NumericBoolean = 0 | 1 | true | false
+export type NumericBooleanFalsy = 0 | false
+export type NumericBooleanTruthy = 1 | true
+
+export interface DNSHeader {
+  /**
+   * Transaction ID, typically a random number. Integer whose value is 0 to 65535
+   */
+  ID?: number
+  /**
+   * Query/Response Flag (0 = Query, 1 = Response)
+   */
+  QR?: NumericBoolean
+  /**
+   * Operation Code (0 for standard query)
+   */
+  Opcode?: DNSQueryOpcode
+  /**
+   * Authoritative Answer (set in response)
+   */
+  AA?: NumericBoolean
+  /**
+   * Truncated Flag
+   */
+  TC?: NumericBoolean // Truncation
+  /**
+   * Recursion Desired
+   */
+  RD?: NumericBoolean // Recursion Desired (set in query)
+  /**
+   * Response Code (0 for no error, non-0 for errors)
+   */
+  RCODE?: DNSRcode
+  /**
+   * Number of questions in the query (usually 1)
+   */
+  QDCOUNT?: number
+  /**
+   * Number of answer records in the response
+   */
+  ANCOUNT?: number
+  /**
+   * Number of authority records in the response
+   */
+  NSCOUNT?: number
+  /**
+   * Number of additional records in the response
+   */
+  ARCOUNT?: number
+}
+
+export interface DNSRequestHeader extends DNSHeader {
+  QR: NumericBooleanFalsy // Query/Response Flag (0 = Query)
+  Opcode: DNSQueryOpcode // Operation Code (0 for standard query)
+  AA: NumericBooleanFalsy // Authoritative Answer (0 in query)
+  TC: NumericBooleanFalsy // Truncation (0 for non-truncated)
+  RCODE: typeof DNSRcodes.NOERROR // Response Code (always 0 in query)
+  ANCOUNT: 0 // Number of answer records (always 0 in query)
+  NSCOUNT: 0 // Number of authority records (always 0 in query)
+  ARCOUNT: 0 // Number of additional records (always 0 in query)
+}
+
+export const StandardRequestHeader: Readonly<DNSRequestHeader> = {
+  ID: 0,
+  QR: 0, // Query/Response Flag (0 = Query)
+  Opcode: DNSQueryOpcodes.QUERY, // Operation Code (0 for standard query)
+  AA: 0, // Authoritative Answer (0 in query)
+  TC: 0, // Truncation (0 for non-truncated)
+  RD: 1, // Recursion Desired (1 if recursion is requested)
+  RCODE: DNSRcodes.NOERROR, // Response Code (always 0 in query)
+  QDCOUNT: 1,
+  ANCOUNT: 0,
+  NSCOUNT: 0,
+  ARCOUNT: 0,
+}
+
+export interface DNSResponseHeader extends DNSHeader {
+  QR: NumericBooleanTruthy // Query/Response Flag (1 = Response)
+  Opcode: DNSQueryOpcode // Operation Code (0 for standard query)
+  AA: NumericBoolean // Authoritative Answer (1 if the response is authoritative)
+  TC: NumericBoolean // Truncation (1 if the message is truncated)
+  RA: NumericBoolean // Recursion Available (1 if the server supports recursion)
+}

package/src/DNS/types/OperationCodes.ts

@@ -0,0 +1,13 @@
+export type DNSQueryOpcode = 0 | 1 | 2 | 4 | 5 | 6 // Supported opcodes as numeric values
+
+// Optional: Add a more descriptive union type for the opcodes.
+export type DNSQueryOpcodeName = 'QUERY' | 'IQUERY' | 'STATUS' | 'NOTIFY' | 'UPDATE' | 'DSO'
+
+export const DNSQueryOpcodes: Record<DNSQueryOpcodeName, DNSQueryOpcode> = {
+  QUERY: 0,
+  IQUERY: 1,
+  STATUS: 2,
+  NOTIFY: 4,
+  UPDATE: 5,
+  DSO: 6,
+}

package/src/DNS/types/Record.ts

@@ -0,0 +1,9 @@
+/* eslint-disable @typescript-eslint/member-ordering */
+import type { DNSResourceRecordTypeValue } from './ResourceRecord.ts'
+
+export interface DNSRecord {
+  name: string // The domain name that was queried
+  type: DNSResourceRecordTypeValue // The record type (e.g., 1 for A record)
+  TTL: number // Time to Live (how long the record can be cached)
+  data: string // The actual data, such as an IP address or TXT record
+}

package/src/DNS/types/Request.ts

@@ -0,0 +1,38 @@
+/* eslint-disable @typescript-eslint/member-ordering */
+import { type DNSRequestHeader, StandardRequestHeader } from './Header.ts'
+import type { DNSResourceRecordTypeValue } from './ResourceRecord.ts'
+import { DNSResourceRecordTypes } from './ResourceRecord.ts'
+
+export interface DNSQuestion {
+  name: string // The domain name that was queried
+  type: DNSResourceRecordTypeValue // The record type (e.g., 1 for A record)
+  class?: number // Query Class (typically 1 for IN - Internet)
+}
+
+export interface DNSRequestFields extends DNSRequestHeader {
+  Question: DNSQuestion[]
+}
+
+/**
+ * Helper for generating a DNS request for a given domain and record type
+ * @param domain The domain to query
+ * @param type The record type to query
+ * @returns A DNS request
+ */
+export const getRequestFor = (domain: string, type: DNSResourceRecordTypeValue = DNSResourceRecordTypes.A): DNSRequestFields => {
+  return {
+    ...StandardRequestHeader,
+    ID: getRandomId(),
+    Question: [{
+      name: domain, type, class: 1,
+    }],
+  }
+}
+
+/**
+ * Used to generate a random ID for a DNS request
+ * @returns A random number between 0 and 65,535
+ */
+export const getRandomId = (): number => {
+  return Math.floor(Math.random() * 65_536) // Math.random() generates a number between 0 and 1, multiply by 65536 to get the range 0-65535
+}

package/src/DNS/types/ResourceRecord.ts

@@ -0,0 +1,229 @@
+// https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-4
+
+export type DNSResourceRecordType =
+  | 'A'
+  | 'NS'
+  | 'MD'
+  | 'MF'
+  | 'CNAME'
+  | 'SOA'
+  | 'MB'
+  | 'MG'
+  | 'MR'
+  | 'NULL'
+  | 'WKS'
+  | 'PTR'
+  | 'HINFO'
+  | 'MINFO'
+  | 'MX'
+  | 'TXT'
+  | 'RP'
+  | 'AFSDB'
+  | 'X25'
+  | 'ISDN'
+  | 'RT'
+  | 'NSAP'
+  | 'NSAP-PTR'
+  | 'SIG'
+  | 'KEY'
+  | 'PX'
+  | 'GPOS'
+  | 'AAAA'
+  | 'LOC'
+  | 'NXT'
+  | 'EID'
+  | 'NIMLOC'
+  | 'SRV'
+  | 'ATMA'
+  | 'NAPTR'
+  | 'KX'
+  | 'CERT'
+  | 'A6'
+  | 'DNAME'
+  | 'SINK'
+  | 'OPT'
+  | 'APL'
+  | 'DS'
+  | 'SSHFP'
+  | 'IPSECKEY'
+  | 'RRSIG'
+  | 'NSEC'
+  | 'DNSKEY'
+  | 'DHCID'
+  | 'NSEC3'
+  | 'NSEC3PARAM'
+  | 'TLSA'
+  | 'SMIMEA'
+  | 'HIP'
+  | 'NINFO'
+  | 'RKEY'
+  | 'TALINK'
+  | 'CDS'
+  | 'CDNSKEY'
+  | 'OPENPGPKEY'
+  | 'CSYNC'
+  | 'ZONEMD'
+  | 'SVCB'
+  | 'HTTPS'
+  | 'SPF'
+  | 'UINFO'
+  | 'UID'
+  | 'GID'
+  | 'UNSPEC'
+  | 'NID'
+  | 'L32'
+  | 'L64'
+  | 'LP'
+  | 'EUI48'
+  | 'EUI64'
+  | 'NXNAME'
+  | 'TKEY'
+  | 'TSIG'
+  | 'IXFR'
+  | 'AXFR'
+  | 'MAILB'
+  | 'MAILA'
+  | '*'
+  | 'URI'
+  | 'CAA'
+  | 'AVC'
+  | 'DOA'
+  | 'AMTRELAY'
+  | 'RESINFO'
+  | 'WALLET'
+  | 'CLA'
+  | 'IPN'
+  | 'TA'
+  | 'DLV'
+  // NOTE: Custom types here
+  | 'XYOA'
+  | 'XYOH'
+
+export const DNSResourceRecordTypes: Readonly<Record<DNSResourceRecordType, number>> = {
+  'A': 1, // a host address
+  'NS': 2, // an authoritative name server
+  'MD': 3, // a mail destination (OBSOLETE - use MX)
+  'MF': 4, // a mail forwarder (OBSOLETE - use MX)
+  'CNAME': 5, // the canonical name for an alias
+  'SOA': 6, // marks the start of a zone of authority
+  'MB': 7, // a mailbox domain name (EXPERIMENTAL)
+  'MG': 8, // a mail group member (EXPERIMENTAL)
+  'MR': 9, // a mail rename domain name (EXPERIMENTAL)
+  'NULL': 10, // a null RR (EXPERIMENTAL)
+  'WKS': 11, // a well known service description
+  'PTR': 12, // a domain name pointer
+  'HINFO': 13, // host information
+  'MINFO': 14, // mailbox or mail list information
+  'MX': 15, // mail exchange
+  'TXT': 16, // text strings
+  'RP': 17, // for Responsible Person
+  'AFSDB': 18, // for AFS Data Base location
+  'X25': 19, // for X.25 PSDN address
+  'ISDN': 20, // for ISDN address
+  'RT': 21, // for Route Through
+  'NSAP': 22, // for NSAP address, NSAP style A record (DEPRECATED)
+  'NSAP-PTR': 23, // for domain name pointer, NSAP style (DEPRECATED)
+  'SIG': 24, // for security signature
+  'KEY': 25, // for security key
+  'PX': 26, // X.400 mail mapping information
+  'GPOS': 27, // Geographical Position
+  'AAAA': 28, // IP6 Address
+  'LOC': 29, // Location Information
+  'NXT': 30, // Next Domain (OBSOLETE)
+  'EID': 31, // Endpoint Identifier
+  'NIMLOC': 32, // Nimrod Locator
+  'SRV': 33, // Server Selection
+  'ATMA': 34, // ATM Address
+  'NAPTR': 35, // Naming Authority Pointer
+  'KX': 36, // Key Exchanger
+  'CERT': 37, // CERT
+  'A6': 38, // A6 (OBSOLETE - use AAAA)
+  'DNAME': 39, // DNAME
+  'SINK': 40, // SINK
+  'OPT': 41, // OPT
+  'APL': 42, // APL
+  'DS': 43, // Delegation Signer
+  'SSHFP': 44, // SSH Key Fingerprint
+  'IPSECKEY': 45, // IPSECKEY
+  'RRSIG': 46, // RRSIG
+  'NSEC': 47, // NSEC
+  'DNSKEY': 48, // DNSKEY
+  'DHCID': 49, // DHCID
+  'NSEC3': 50, // NSEC3
+  'NSEC3PARAM': 51, // NSEC3PARAM
+  'TLSA': 52, // TLSA
+  'SMIMEA': 53, // S/MIME cert association
+  'HIP': 55, // Host Identity Protocol
+  'NINFO': 56, // NINFO
+  'RKEY': 57, // RKEY
+  'TALINK': 58, // Trust Anchor LINK
+  'CDS': 59, // Child DS
+  'CDNSKEY': 60, // DNSKEY(s) the Child wants reflected in DS
+  'OPENPGPKEY': 61, // OpenPGP Key
+  'CSYNC': 62, // Child-To-Parent Synchronization
+  'ZONEMD': 63, // Message Digest Over Zone Data
+  'SVCB': 64, // General-purpose service binding
+  'HTTPS': 65, // SVCB-compatible type for use with HTTP
+  'SPF': 99,
+  'UINFO': 100,
+  'UID': 101,
+  'GID': 102,
+  'UNSPEC': 103,
+  'NID': 104,
+  'L32': 105,
+  'L64': 106,
+  'LP': 107,
+  'EUI48': 108, // an EUI-48 address
+  'EUI64': 109, // an EUI-64 address
+  'NXNAME': 128, // NXDOMAIN indicator for Compact Denial of Existence
+  'TKEY': 249, // Transaction Key
+  'TSIG': 250, // Transaction Signature
+  'IXFR': 251, // incremental transfer
+  'AXFR': 252, // transfer of an entire zone
+  'MAILB': 253, // mailbox-related RRs (MB, MG or MR)
+  'MAILA': 254, // mail agent RRs (OBSOLETE - see MX)
+  '*': 255, // A request for some or all records the server has available
+  'URI': 256, // URI
+  'CAA': 257, // Certification Authority Restriction
+  'AVC': 258, // Application Visibility and Control
+  'DOA': 259, // Digital Object Architecture
+  'AMTRELAY': 260, // Automatic Multicast Tunneling Relay
+  'RESINFO': 261, // Resolver Information as Key/Value Pairs
+  'WALLET': 262, // Public wallet address
+  'CLA': 263, // BP Convergence Layer Adapter
+  'IPN': 264, // BP Node Number
+  'TA': 32_768, // DNSSEC Trust Authorities
+  'DLV': 32_769, // DNSSEC Lookaside Validation (OBSOLETE)
+
+  // NOTE: Custom types here chosen within the Private Use Range
+  // https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-4
+  // https://www.rfc-editor.org/rfc/rfc5226
+  // as, per the RFC, the Private Use Range is reserved
+  // "For private or local use only, with the type and
+  // purpose defined by the local site.  No attempt is made to
+  // prevent multiple sites from using the same value in
+  // different (and incompatible) ways.  There is no need for
+  // IANA to review such assignments (since IANA does not record
+  // them) and assignments are not generally useful for broad
+  // interoperability.  It is the responsibility of the sites
+  // making use of the Private Use range to ensure that no
+  // conflicts occur (within the intended scope of use)."
+  // If we want to apply for a custom reserved code later
+  // on, once the usage is proven enough we can absolutely
+  // do that.
+  'XYOA': 65_432, // XYO Address
+  'XYOH': 65_433, // XYO Hash
+}
+
+export type DNSResourceRecordTypeValue = (typeof DNSResourceRecordTypes)[keyof typeof DNSResourceRecordTypes]
+
+export const findDNSResourceRecordTypesByValue = (value: DNSResourceRecordTypeValue): DNSResourceRecordType | undefined => {
+  // Iterate through the keys of the record
+  for (const key in DNSResourceRecordTypes) {
+    const resourceRecordType = key as DNSResourceRecordType
+    if (DNSResourceRecordTypes[resourceRecordType] === value) {
+      return resourceRecordType // Return the key if the value matches
+    }
+  }
+  return undefined // Return undefined if no matching value is found
+}

package/src/DNS/types/Response.ts

@@ -0,0 +1,12 @@
+import type { DNSAnswer } from './Answer.ts'
+import type { DNSResponseHeader } from './Header.ts'
+import type { DNSRecord } from './Record.ts'
+import type { DNSQuestion } from './Request.ts'
+
+/* eslint-disable @typescript-eslint/member-ordering */
+export interface DNSResponseFields extends DNSResponseHeader {
+  Question: DNSQuestion[] // The questions that were asked
+  Answer: DNSAnswer[] // Reusing DNSAnswer for the Answer Section
+  Authority?: DNSRecord[]
+  Additional?: DNSRecord[]
+}

package/src/DNS/types/ResponseCodes.ts

@@ -0,0 +1,34 @@
+export type DNSRcode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 16 | 17 | 18
+
+export type DNSRcodeName =
+  | 'NOERROR'
+  | 'FORMERR'
+  | 'SERVFAIL'
+  | 'NXDOMAIN'
+  | 'NOTIMP'
+  | 'REFUSED'
+  | 'YXDOMAIN'
+  | 'YXRRSET'
+  | 'NXRRSET'
+  | 'NOTAUTH'
+  | 'NOTZONE'
+  | 'BADSIG'
+  | 'BADKEY'
+  | 'BADTIME'
+
+export const DNSRcodes: Readonly<Record<DNSRcodeName, DNSRcode>> = {
+  NOERROR: 0,
+  FORMERR: 1,
+  SERVFAIL: 2,
+  NXDOMAIN: 3,
+  NOTIMP: 4,
+  REFUSED: 5,
+  YXDOMAIN: 6,
+  YXRRSET: 7,
+  NXRRSET: 8,
+  NOTAUTH: 9,
+  NOTZONE: 10,
+  BADSIG: 16,
+  BADKEY: 17,
+  BADTIME: 18,
+}

package/src/DNS/types/index.ts

@@ -0,0 +1,8 @@
+export * from './Answer.ts'
+export * from './Header.ts'
+export * from './OperationCodes.ts'
+export * from './Record.ts'
+export * from './Request.ts'
+export * from './ResourceRecord.ts'
+export * from './Response.ts'
+export * from './ResponseCodes.ts'

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './Address/index.ts'
 export * from './diviner/index.ts'
+export * from './DNS/index.ts'
 export * from './Domain/index.ts'
 export * from './DomainRegistration/index.ts'
 export * from './Duration/index.ts'