@onoal/oid-core

Pure, namespace-agnostic implementation of OID Core v0.1.1.

Overview

@onoal/oid-core is a zero-dependency TypeScript library that implements the OID Core v0.1.1 specification. It provides the fundamental building blocks for working with OID (Onoal Identity) identifiers and records.

What it does

✅ OID Identifier Parsing & Validation

• Parse OID strings (oid:<namespace>:<path>)
• Validate syntax and normalize to canonical lowercase form
• Type-safe Oid class

✅ Record Structure & Validation

• Complete TypeScript types for OID records
• Validate records against v0.1.1 spec
• Check schema, keys, timestamps, and proof

✅ Cryptographic Operations

• Ed25519 signing and verification
• JSON Canonicalization Scheme (JCS)
• Base64url encoding/decoding

What it does NOT do

❌ Network/HTTP resolution
❌ Ledger integration
❌ Namespace-specific business logic (see @onoal/oid-onoal)

Installation

npm install @onoal/oid-core
# or
pnpm add @onoal/oid-core
# or
yarn add @onoal/oid-core

Quick Start

1. Parse an OID Identifier

import { Oid } from '@onoal/oid-core';

// Parse and validate
const oid = Oid.parse('oid:onoal:user:6w9f4k2h3p');

console.log(oid.namespace);  // "onoal"
console.log(oid.segments);   // ["user", "6w9f4k2h3p"]
console.log(oid.toString()); // "oid:onoal:user:6w9f4k2h3p"

// Compare OIDs (case-insensitive)
const oid2 = Oid.parse('OID:ONOAL:USER:6W9F4K2H3P');
console.log(oid.equals(oid2)); // true (normalized to lowercase)

2. Create and Sign a Record

import {
  generateEd25519KeyPair,
  signOidRecord,
  type OidRecordWithoutProof,
} from '@onoal/oid-core';

// Generate keypair
const { privateKey, publicKey } = await generateEd25519KeyPair();

// Create unsigned record
const record: OidRecordWithoutProof = {
  oid: 'oid:example:user:alice',
  schema: 'oid-core/v0.1.1',
  kind: 'human',
  keys: [{
    id: '#main',
    usage: ['auth', 'sign', 'control'],
    alg: 'ed25519',
    publicKey: base64urlEncode(publicKey),
    createdAt: new Date().toISOString(),
  }],
  metadata: {
    displayName: 'Alice',
  },
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString(),
};

// Sign the record
const signedRecord = await signOidRecord(record, {
  keyId: '#main',
  privateKey,
});

console.log(signedRecord.proof); // Contains signature

3. Verify a Record

import { verifyRecord } from '@onoal/oid-core';

const result = await verifyRecord(signedRecord);

if (result.valid) {
  console.log('✅ Signature is valid');
} else {
  console.error('❌ Verification failed:', result.errors);
}

4. Validate Record Structure

import { validateRecord } from '@onoal/oid-core';

const validation = validateRecord(record);

if (validation.valid) {
  console.log('✅ Record structure is valid');
} else {
  console.error('❌ Validation errors:', validation.errors);
}

API Reference

Types

// Core types
export type OidString = string;
export type OidKind = "human" | "org" | "service" | "device" | "key" | "asset";
export type KeyUsage = "auth" | "sign" | "encrypt" | "control";
export type KeyAlgorithm = "ed25519";
export type ProofType = "ed25519-jcs-2025";

export interface OidRecord { /* ... */ }
export interface OidKey { /* ... */ }
export interface OidProof { /* ... */ }
export interface OidMetadata { /* ... */ }

Classes

Oid

class Oid {
  static parse(input: string): Oid;
  get namespace(): string;
  get segments(): string[];
  toString(): string;
  equals(other: Oid): boolean;
}

Functions

OID Parsing

function validateOidSyntax(oid: string): ValidationResult;
function normalizeOid(oid: string): string;
function oidsEqual(oid1: string, oid2: string): boolean;

Record Validation

function validateRecord(record: unknown): ValidationResult;

Cryptography

// Signing
function signOidRecord(
  record: OidRecordWithoutProof,
  options: SignOptions
): Promise<OidRecord>;

function generateEd25519KeyPair(): Promise<{
  privateKey: Uint8Array;
  publicKey: Uint8Array;
}>;

// Verification
function verifyRecord(record: OidRecord): Promise<VerificationResult>;

function verifySignature(
  message: Uint8Array,
  signature: Uint8Array,
  publicKey: Uint8Array
): Promise<boolean>;

// Canonicalization
function jcsStringify(value: unknown): string;
function canonicalizeWithoutProof(record: unknown): Uint8Array;
function base64urlEncode(bytes: Uint8Array): string;
function base64urlDecode(str: string): Uint8Array;

Advanced Usage

Custom Namespace

This library is namespace-agnostic. You can use any namespace:

const myOid = Oid.parse('oid:mycompany:product:xyz123');
console.log(myOid.namespace); // "mycompany"

Manual Canonicalization

import { canonicalizeWithoutProof } from '@onoal/oid-core';

const canonical = canonicalizeWithoutProof(record);
// Returns UTF-8 encoded bytes of deterministic JSON

Low-Level Signature Verification

import { verifySignature, base64urlDecode } from '@onoal/oid-core';

const message = new TextEncoder().encode('Hello, World!');
const signature = base64urlDecode('...');
const publicKey = base64urlDecode('...');

const isValid = await verifySignature(message, signature, publicKey);

Specification Compliance

This package implements:

• OID Core v0.1.1 — Complete specification
• Ed25519 — RFC 8032 signatures
• JCS — JSON Canonicalization Scheme
• Base64url — RFC 4648 URL-safe encoding

See: specs/oid-core-v0.1.1.md

Bundle Size

• ~50 KB minified (including @noble/ed25519)
• Tree-shakeable ESM exports
• Zero dependencies except cryptography

Browser Support

Works in all modern browsers and Node.js ≥18:

• ✅ Chrome/Edge (latest)
• ✅ Firefox (latest)
• ✅ Safari (latest)
• ✅ Node.js 18+

Related Packages

• @onoal/oid-onoal — Onoal-specific helpers and conventions
• @onoal/oid-resolver (planned) — HTTP/DNS resolution
• @onoal/oid-ledger (planned) — Nucleus ledger integration

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT © Onoal