How to Use the Identity Library

This guide explains how to use the SEA™ Identity Library for generating pre-mint and attested identities per SDS-050.

Overview

SEA™ uses a dual-state identity model:

Identity Type Format Purpose
Pre-mint ifl:hash:<sha256> Content-addressed, offline-capable
Attested ifl:token:<ledger>:<seq> Ledger-backed, immutable

Installation

The identity library is part of @sea/domain:

1

import { computePreMintIdentity, parseIdentity } from '@sea/domain/identity';

Generating Pre-Mint Identities

1
2
3
4
5
6
7
8
9
10
11
12
13

import { computePreMintIdentity, SemanticArtifact } from '@sea/domain/identity';

const artifact: SemanticArtifact = {
  type: 'Concept',
  namespace: 'com.example.billing',
  name: 'Invoice',
  version: 'v1.0.0',
};

const identity = computePreMintIdentity(artifact);

console.log(identity.uri);
// → "ifl:hash:a3f2c8d9e1b4567890abcdef..."

Invariants (SDS-050)

Invariant Rule
I-PM-01 Same artifact → same hash across environments
I-PM-02 No network access required
I-PM-03 Hash changes if artifact changes
I-PM-04 No timestamps or env data in hash

Parsing Identities

1
2
3
4
5
6
7
8
9
10

import { parseIdentity, isPreMintIdentity, isAttestedIdentity } from '@sea/domain/identity';

const uri = 'ifl:hash:a3f2c8d9e1b4567890abcdef1234567890abcdef1234567890abcdef12345678';
const identity = parseIdentity(uri);

if (isPreMintIdentity(identity)) {
  console.log('Pre-mint:', identity.hash);
} else if (isAttestedIdentity(identity)) {
  console.log('Attested:', identity.ledgerId, identity.sequenceNumber);
}

Validating Identities

1
2
3
4

import { isValidIdentity } from '@sea/domain/identity';

isValidIdentity('ifl:hash:a3f2...');  // → true
isValidIdentity('invalid');           // → false

Canonical Normalization

The identity hash is computed from a canonically normalized artifact:

1
2
3
4
5
6
7

import { normalizeCanonical } from '@sea/domain/identity';

const bytes = normalizeCanonical(artifact, {
  sortKeys: true,       // Alphabetical key ordering
  compactJson: true,    // No extra whitespace
  normalizeUnicode: true // NFC form
});

Artifact Types

1
2
3
4
5
6
7
8

type ArtifactType =
  | 'Concept'
  | 'Policy'
  | 'Entity'
  | 'Resource'
  | 'Flow'
  | 'NormalizerRule'
  | 'IdentitySchema';