@hackfed/schemas 0.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Hackfed Team & Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# Schemas • Hackfed
+
+This repository contains JSON Schemas for Resource Definiton Schemas used in Hackfed.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@hackfed/schemas",
+  "version": "0.0.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./*": "./src/schemas/*"
+  },
+  "files": [
+    "src/schemas",
+    "LICENSE",
+    "README"
+  ],
+  "devDependencies": {
+    "@bksp/style-guide": "^1.2.6",
+    "@tsconfig/strictest": "^2.0.8",
+    "@types/node": "^25.0.9",
+    "change-case": "^5.4.4",
+    "eslint": "^9.39.2",
+    "glob": "^13.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "zod": "4"
+  },
+  "peerDependencies": {
+    "zod": "4"
+  },
+  "scripts": {
+    "generate": "tsx src/cmd/generate-json-schemas.ts"
+  }
+}

package/src/schemas/index.ts

@@ -0,0 +1 @@
+/* eslint-disable-next-line unicorn/no-empty-file -- this is a stub file. */

package/src/schemas/v1/base/inet6-number.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+
+export const Inet6NumberSchema = z
+  .string()
+  .regex(
+    /^(((?:[0-9A-Fa-f]{1,4}))*((?::[0-9A-Fa-f]{1,4}))*::((?:[0-9A-Fa-f]{1,4}))*((?::[0-9A-Fa-f]{1,4}))*|((?:[0-9A-Fa-f]{1,4}))((?::[0-9A-Fa-f]{1,4})){7})(\/([1-9]|[1-9][0-9]|1[0-1][0-9]|12[0-8])){0,1}$/
+  )
+  .meta({
+    description: 'An IPv6 address in standard notation',
+    examples: ['fd79:7636:1f08:883d::008', '2001:db8::1', '::1', 'fe80::1/128'],
+    id: 'Inet6Number',
+    title: 'IPv6 Address',
+  })
+
+export type Inet6Number = z.infer<typeof Inet6NumberSchema>
+
+export const __schemas = [Inet6NumberSchema]

package/src/schemas/v1/base/organization-id.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+
+export const OrganizationIdSchema = z
+  .string()
+  .regex(/^[a-z0-9]*$/)
+  .min(4)
+  .max(16)
+  .meta({
+    description: 'A unique identifier for an organization in the Hackfed registry',
+    examples: ['bksp', 'xkem'],
+    id: 'OrganizationId',
+    title: 'Organization ID',
+  })
+
+export type OrganizationId = z.infer<typeof OrganizationIdSchema>
+
+export const __schemas = [OrganizationIdSchema]

package/src/schemas/v1/directory/telephony.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod'
+
+import { OrganizationIdSchema } from '../base/organization-id'
+
+export const DirectoryExchangeSchema = z
+  .object({
+    codecs: z
+      .array(z.enum(['opus', 'g722', 'ulaw']))
+      .min(1)
+      .describe('Supported audio codecs'),
+    endpoint: z
+      .string()
+      .describe('Network address and port of the exchange (e.g., [IPv6]:port or IPv4:port)'),
+    id: z.string().describe('Unique exchange identifier within the organization'),
+    prefixes: z
+      .array(z.e164().describe('Telephony number prefix (e.g., country or area code)'))
+      .describe('Telephony number prefixes allocated to the organization for this exchange'),
+    protocol: z.enum(['iax2']).describe('Telephony protocol used by the exchange'),
+  })
+  .strict()
+
+export const DirectoryOrgSchema = z
+  .object({
+    exchanges: z
+      .array(DirectoryExchangeSchema)
+      .describe('List of telephony exchanges for the organization'),
+    name: z.string().describe('Name of the organization'),
+    orgId: OrganizationIdSchema.describe('Unique identifier for the organization'),
+  })
+  .strict()
+
+export const TelephonyDirectorySchema = z
+  .object({
+    orgs: z
+      .array(DirectoryOrgSchema)
+      .describe('List of organizations participating in Hackfed Telephony Network.'),
+  })
+  .meta({
+    description: 'Aggregated telephony service information for Hackfed network members.',
+    id: 'TelephonyDirectory',
+    title: 'Hackfed Telephony Directory',
+  })
+
+export type TelephonyDirectory = z.infer<typeof TelephonyDirectorySchema>
+export type DirectoryOrg = z.infer<typeof DirectoryOrgSchema>
+export type DirectoryExchange = z.infer<typeof DirectoryExchangeSchema>
+
+export const __schemas = [TelephonyDirectorySchema]

package/src/schemas/v1/entity/organization.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod'
+
+import { OrganizationIdSchema } from '../base/organization-id'
+import { AboutServiceSchema } from '../service/about'
+import { AccessServiceSchema } from '../service/access'
+import { NebulaServiceSchema } from '../service/nebula'
+import { TelephonyServiceSchema } from '../service/telephony'
+
+export const OrganizationSchema = z
+  .object({
+    apiVersion: z.literal('hackfed/v1').describe('API version identifier'),
+    kind: z.literal('Organization').describe('Resource type'),
+    metadata: z
+      .object({
+        orgId: OrganizationIdSchema.describe('Identifier of the organization owning this resource'),
+      })
+      .describe('Metadata about the organization'),
+    spec: z
+      .object({
+        id: OrganizationIdSchema.describe('Organization ID (must match metadata.orgId)'),
+        name: z
+          .string()
+          .min(4)
+          .max(64)
+          .describe('Human-readable organization name'),
+        services: z
+          .object({
+            about: AboutServiceSchema.optional(),
+            access: AccessServiceSchema.optional(),
+            nebula: NebulaServiceSchema.optional(),
+            telephony: TelephonyServiceSchema.optional(),
+          })
+          .describe('Services provided by the organization')
+          .optional(),
+      })
+      .strict()
+      .describe('Organization specification'),
+  })
+  .meta({
+    description: 'Complete organization entity definition for Hackfed registry',
+    id: 'Organization',
+    title: 'Hackfed Organization',
+  })
+
+export type Organization = z.infer<typeof OrganizationSchema>
+
+export const __schemas = [OrganizationSchema]

package/src/schemas/v1/service/about.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod'
+
+export const AboutServiceSchema = z
+  .object({
+    contact: z
+      .object({
+        email: z.email().describe("Organization's contact email address").optional(),
+        website: z.url().describe("Organization's website URL").optional(),
+      })
+      .strict()
+      .describe('Contact information for the organization')
+      .optional(),
+  })
+  .strict()
+  .meta({
+    description: 'Contact information and general details about an organization',
+    id: 'AboutService',
+    title: 'Organization About Service',
+  })
+
+export type AboutService = z.infer<typeof AboutServiceSchema>
+
+export const __schemas = [AboutServiceSchema]

package/src/schemas/v1/service/access.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod'
+
+export const GithubMaintainerSchema = z
+  .object({
+    type: z.literal('github'),
+    username: z.string().describe('Username for GitHub type maintainers'),
+  })
+  .describe('Maintainer identified by GitHub username')
+
+export const EmailMaintainerSchema = z
+  .object({
+    email: z.email().describe('Email address for email type maintainers'),
+    type: z.literal('email'),
+  })
+  .describe('Maintainer identified by email address')
+
+export const MaintainerSchema = z.discriminatedUnion('type', [
+  GithubMaintainerSchema,
+  EmailMaintainerSchema,
+])
+
+export const AccessServiceSchema = z
+  .object({
+    maintainers: z
+      .array(MaintainerSchema)
+      .min(1)
+      .describe('List of organization maintainers')
+      .optional(),
+  })
+  .strict()
+  .meta({
+    description: 'Access control and maintainer information for an organization',
+    id: 'AccessService',
+    title: 'Organization Access Service',
+  })
+
+export type AccessService = z.infer<typeof AccessServiceSchema>
+export type Maintainer = z.infer<typeof MaintainerSchema>
+export type GithubMaintainer = z.infer<typeof GithubMaintainerSchema>
+export type EmailMaintainer = z.infer<typeof EmailMaintainerSchema>
+
+export const __schemas = [AccessServiceSchema]

package/src/schemas/v1/service/nebula.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod'
+
+import { Inet6NumberSchema } from '../base/inet6-number'
+
+export const NebulaNodeSchema = z
+  .object({
+    address: Inet6NumberSchema.describe('IPv6 address of the Nebula node'),
+    certificates: z
+      .array(
+        z
+          .string()
+          .regex(/^[a-f0-9]{64}$/)
+          .describe('SHA-256 certificate fingerprint in hexadecimal')
+      )
+      .min(1)
+      .describe('List of certificate fingerprints for the node')
+      .optional(),
+    lighthouse: z
+      .object({
+        enabled: z.boolean().describe('Whether this node acts as a lighthouse'),
+        endpoints: z
+          .array(z.string().describe('Endpoint in format host:port'))
+          .min(1)
+          .describe('Public endpoints for lighthouse connectivity')
+          .optional(),
+      })
+      .strict()
+      .describe('Lighthouse configuration for the node')
+      .optional(),
+  })
+  .strict()
+
+export const NebulaServiceSchema = z.array(NebulaNodeSchema).meta({
+  description: 'Nebula VPN network configuration for the organization',
+  id: 'NebulaService',
+  title: 'Organization Nebula Service',
+})
+
+export type NebulaService = z.infer<typeof NebulaServiceSchema>
+export type NebulaNode = z.infer<typeof NebulaNodeSchema>
+
+export const __schemas = [NebulaServiceSchema]

package/src/schemas/v1/service/telephony.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+
+export const ExchangeSchema = z
+  .object({
+    address: z
+      .string()
+      .describe('Network address and port of the exchange (e.g., [IPv6]:port or IPv4:port)'),
+    codecs: z
+      .array(z.enum(['opus', 'g722', 'ulaw']))
+      .min(1)
+      .describe('Supported audio codecs'),
+    id: z.string().describe('Unique identifier for the exchange'),
+    protocol: z.enum(['iax2']).describe('Telephony protocol used by the exchange'),
+  })
+  .strict()
+
+export const PrefixSchema = z
+  .object({
+    description: z.string().describe('Human-readable description of the prefix').optional(),
+    exchange: z.string().describe('Reference to the exchange ID handling this prefix'),
+    id: z.string().describe('Unique identifier for the prefix'),
+    prefix: z.e164().describe('Numeric prefix for phone numbers'),
+  })
+  .strict()
+
+export const PhonebookSchema = z
+  .object({
+    format: z.enum(['hackfed']).describe('Format of the phonebook data'),
+    url: z.url().describe('URL to the phonebook resource'),
+  })
+  .strict()
+
+export const TelephonyServiceSchema = z
+  .object({
+    exchanges: z.array(ExchangeSchema).describe('List of telephony exchanges').optional(),
+    phonebook: z.array(PhonebookSchema).describe('Public phonebook URLs').optional(),
+    prefixes: z
+      .array(PrefixSchema)
+      .describe('Telephony number prefixes allocated to the organization')
+      .optional(),
+  })
+  .strict()
+  .meta({
+    description: 'Telephony configuration including exchanges, prefixes, and phonebook',
+    id: 'TelephonyService',
+    title: 'Organization Telephony Service',
+  })
+
+export type TelephonyService = z.infer<typeof TelephonyServiceSchema>
+export type Exchange = z.infer<typeof ExchangeSchema>
+export type Prefix = z.infer<typeof PrefixSchema>
+export type Phonebook = z.infer<typeof PhonebookSchema>
+
+export const __schemas = [TelephonyServiceSchema]