@owf/eudi-lote 0.0.0

package/README.md

@@ -0,0 +1,384 @@
+# @owf/eudi-lote
+
+SDK for creating, signing, and managing Lists of Trusted Entities (LoTE) per **ETSI TS 119 602**.
+
+## Overview
+
+This SDK implements the ETSI TS 119 602 standard for LoTE documents, enabling:
+
+- **Create and manage LoTE documents** with trusted entities and their services
+- **Sign LoTE documents** with private keys or custom signers (HSM/KMS)
+- **Validate LoTE documents** against ETSI TS 119 602 schema
+
+> **Note**: This package currently supports **JWT encoding only**. CBOR and XML encodings are not yet supported.
+
+## Specification Reference
+
+- [ETSI TS 119 602](https://www.etsi.org/deliver/etsi_ts/119600_119699/119602/01.01.01_60/ts_119602v010101p.pdf) - Trusted Lists
+
+## Installation
+
+```bash
+npm install @owf/eudi-lote
+# or
+pnpm add @owf/eudi-lote
+```
+
+## Usage
+
+### Creating a LoTE Document
+
+```typescript
+import {
+  createLoTE,
+  trustedEntity,
+  service,
+  addTrustedEntity,
+} from '@owf/eudi-lote';
+
+// Create the base LoTE document (only SchemeOperatorName is required)
+let lote = createLoTE({
+  SchemeOperatorName: [{ lang: 'en', value: 'Example Trust Operator' }],
+  SchemeOperatorAddress: {
+    SchemeOperatorPostalAddress: [
+      {
+        lang: 'en',
+        StreetAddress: 'Main Street 1',
+        Locality: 'Berlin',
+        PostalCode: '10115',
+        Country: 'DE',
+      },
+    ],
+    SchemeOperatorElectronicAddress: [
+      { lang: 'en', uriValue: 'mailto:trust@example.org' },
+    ],
+  },
+  SchemeName: [{ lang: 'en', value: 'Gym Membership Issuers' }],
+  SchemeTerritory: 'DE',
+});
+
+// Build a trusted entity using the fluent builder
+const gymEntity = trustedEntity()
+  .name('Mighty Fitness Center GmbH')
+  .tradeName('Mighty Fitness')
+  .postalAddress({
+    StreetAddress: 'Gym Street 5',
+    Locality: 'Fitville',
+    PostalCode: '54321',
+    Country: 'DE',
+  })
+  .email('contact@gym.example.com')
+  .website('https://gym.example.com')
+  .infoUri('https://gym.example.com/about')
+  .addService(
+    service()
+      .name('Gym Membership Attestation Issuance')
+      .type('https://example.org/service-type/gym-attestation-issuer')
+      .status('https://example.org/status/granted')
+      .addPublicKey({
+        kty: 'EC',
+        crv: 'P-256',
+        x: '...',
+        y: '...',
+        kid: 'gym-issuer-key-1',
+        use: 'sig',
+        alg: 'ES256',
+      })
+      .addEndpoint(
+        'https://example.org/service-type/gym-attestation-issuer',
+        'https://issuer.gym.example.com',
+      )
+      .build(),
+  )
+  .build();
+
+// Add the entity to the LoTE document
+lote = addTrustedEntity(lote, gymEntity);
+```
+
+### Service with Multiple Identity Types
+
+The SDK supports all digital identity types from ETSI TS 119 602:
+
+```typescript
+const svc = service()
+  .name('Multi-Identity Service')
+  .type('https://example.org/service-type/issuer')
+  .status('https://example.org/status/granted')
+  // X.509 certificates
+  .addCertificate('MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...')
+  // X.509 subject names
+  .addX509SubjectName('CN=Test CA, O=Test Org, C=DE')
+  // X.509 Subject Key Identifiers
+  .addX509SKI('base64encodedSKI==')
+  // JWK public keys
+  .addPublicKey({ kty: 'EC', crv: 'P-256', x: '...', y: '...' })
+  // Other identifiers
+  .addOtherId('urn:example:custom-id:12345')
+  .build();
+```
+
+### Service History
+
+Track historical changes to services:
+
+```typescript
+const svc = service()
+  .name('Current Service Name')
+  .addPublicKey({ kty: 'EC', crv: 'P-256', x: '...', y: '...' })
+  .addHistoryEntry({
+    ServiceName: [{ lang: 'en', value: 'Previous Service Name' }],
+    ServiceDigitalIdentity: { PublicKeyValues: [{ kty: 'EC', crv: 'P-256' }] },
+    ServiceStatus: 'https://example.org/status/revoked',
+    StatusStartingTime: '2023-01-01T00:00:00.000Z',
+  })
+  .build();
+```
+
+### Pointers to Other LoTE Lists
+
+Reference other LoTE documents:
+
+```typescript
+const lote = createLoTE({
+  SchemeOperatorName: [{ lang: 'en', value: 'Master Registry' }],
+  PointersToOtherLoTE: [
+    {
+      LoTELocation: 'https://other-registry.example.com/lote',
+      ServiceDigitalIdentities: [
+        { PublicKeyValues: [{ kty: 'EC', crv: 'P-256', x: '...', y: '...' }] },
+      ],
+      LoTEQualifiers: [
+        {
+          LoTEType: 'https://example.org/lote-type/regional',
+          SchemeOperatorName: [{ lang: 'en', value: 'Regional Operator' }],
+          MimeType: 'application/jwt',
+        },
+      ],
+    },
+  ],
+});
+```
+
+### Signing a LoTE Document
+
+```typescript
+import { signLoTE } from '@owf/eudi-lote';
+import { ES256 } from '@owf/crypto';
+
+// With a local key
+const signer = await ES256.getSigner(privateKeyPem);
+const signed = await signLoTE({
+  lote,
+  keyId: 'lote-signer-2025',
+  signer,
+});
+
+console.log(signed.jws); // The signed JWS
+```
+
+### Using a KMS/HSM Signer
+
+```typescript
+const signed = await signLoTE({
+  lote,
+  keyId: 'lote-signer-2025',
+  signer: async (data) => {
+    return await myKmsService.sign('ES256', data);
+  },
+});
+```
+
+### Validating a LoTE Document
+
+```typescript
+import {
+  validateLoTE,
+  assertValidLoTE,
+} from '@owf/eudi-lote';
+
+// Get validation result with error details
+const result = validateLoTE(lote);
+if (!result.valid) {
+  console.log('Validation errors:', result.errors);
+}
+
+// Or throw on invalid
+assertValidLoTE(lote); // throws ValidationError if invalid
+```
+
+### Updating a LoTE Document
+
+```typescript
+import {
+  updateLoTEVersion,
+  addTrustedEntity,
+  removeTrustedEntity,
+} from '@owf/eudi-lote';
+
+// Increment version and update timestamps
+let updatedList = updateLoTEVersion(lote);
+
+// Add new entity
+updatedList = addTrustedEntity(updatedList, newEntity);
+
+// Remove an entity by name
+updatedList = removeTrustedEntity(updatedList, 'Old Gym Name');
+```
+
+## API Reference
+
+### Signing
+
+#### `signLoTE(options): Promise<SignedLoTE>`
+
+Signs a LoTE document using the provided signer function.
+
+#### `createLoTE(schemeInfo, entities?): LoTEDocument`
+
+Creates a new LoTE document with the given scheme information. Only `SchemeOperatorName` is required per ETSI TS 119 602.
+
+#### `updateLoTEVersion(lote): LoTEDocument`
+
+Increments the sequence number and updates timestamps.
+
+#### `addTrustedEntity(lote, entity): LoTEDocument`
+
+Adds a trusted entity to the list.
+
+#### `removeTrustedEntity(lote, entityName): LoTEDocument`
+
+Removes an entity by name.
+
+### Validation
+
+#### `validateLoTE(lote): ValidationResult`
+
+Validates a LoTE document against ETSI TS 119 602 schema. Returns validation result with error details.
+
+#### `assertValidLoTE(lote): asserts lote is LoTEDocument`
+
+Type assertion that throws `ValidationError` if the LoTE document is invalid.
+
+### Builders
+
+#### `trustedEntity(): TrustedEntityBuilder`
+
+Fluent builder for creating trusted entities.
+
+Methods:
+
+- `.name(name, lang?)` - Entity name
+- `.tradeName(name, lang?)` - Trade name
+- `.registrationId(id, lang?)` - Registration identifier
+- `.postalAddress(address, lang?)` - Postal address
+- `.email(email, lang?)` - Email address
+- `.website(url, lang?)` - Website URL
+- `.infoUri(uri, lang?)` - Information URI
+- `.addExtension(extension)` - Add an extension
+- `.addService(service)` - Add a service
+- `.build()` - Build the entity
+
+#### `service(): ServiceBuilder`
+
+Fluent builder for creating services.
+
+Methods:
+
+- `.name(name, lang?)` - Service name
+- `.type(typeUri)` - Service type identifier
+- `.status(statusUri)` - Service status
+- `.statusStartingTime(isoTimestamp)` - When status became effective
+- `.addCertificate(base64Cert)` - Add X.509 certificate
+- `.addX509SubjectName(subjectName)` - Add X.509 subject name
+- `.addX509SKI(base64SKI)` - Add X.509 Subject Key Identifier
+- `.addPublicKey(jwk)` - Add JWK public key
+- `.addOtherId(identifier)` - Add custom identifier
+- `.addEndpoint(type, uri)` - Add service endpoint
+- `.addExtension(extension)` - Add service extension
+- `.addHistoryEntry(entry)` - Add service history entry
+- `.build()` - Build the service
+
+## Types
+
+See [src/types.ts](./src/types.ts) for complete type definitions including:
+
+- `LoTEDocument` - Root LoTE document structure
+- `TrustedEntity` - Entity in the LoTE document
+- `Service` - Service provided by an entity
+- `ServiceDigitalIdentity` - Digital identity for a service
+- `ServiceHistory` / `ServiceHistoryInstance` - Historical service states
+- `PointersToOtherLoTE` / `OtherLoTEPointer` - Cross-list references
+- `ValidationResult` / `ValidationError` - Validation types
+
+All document types are derived from Zod schemas. You can import and use the schemas
+directly for custom validation or to build upon:
+
+```typescript
+import { LoTEDocumentSchema, TrustedEntitySchema } from '@owf/eudi-lote';
+
+// Use schemas for custom validation
+const result = LoTEDocumentSchema.safeParse(data);
+
+// Compose with your own schemas
+const mySchema = TrustedEntitySchema.extend({ customField: z.string() });
+```
+
+### SignerFunction
+
+```typescript
+type SignerFunction = (data: Uint8Array) => Promise<Uint8Array | string>;
+```
+
+## External Key Management
+
+The SDK supports delegating signing to external services:
+
+### Azure Key Vault
+
+```typescript
+import { CryptographyClient } from '@azure/keyvault-keys';
+
+const signed = await signLoTE({
+  lote,
+  keyId: 'lote-signer',
+  signer: async (data) => {
+    const result = await cryptoClient.sign('ES256', data);
+    return result.result;
+  },
+});
+```
+
+### AWS KMS
+
+```typescript
+import { KMSClient, SignCommand } from '@aws-sdk/client-kms';
+
+const signed = await signLoTE({
+  lote,
+  keyId: 'lote-signer',
+  signer: async (data) => {
+    const response = await kmsClient.send(
+      new SignCommand({
+        KeyId: 'alias/lote-signer',
+        Message: data,
+        MessageType: 'RAW',
+        SigningAlgorithm: 'ECDSA_SHA_256',
+      }),
+    );
+    return new Uint8Array(response.Signature!);
+  },
+});
+```
+
+## Security Considerations
+
+- **Protect signing keys** - Use HSM or KMS for production
+- **Validate trust anchors** - Verify the signer's certificate chain
+- **Check sequence numbers** - Ensure you have the latest version
+- **Use HTTPS** - Always use HTTPS for distribution points
+- **Validate before signing** - Use `assertValidLoTE` before signing
+
+## License
+
+Apache-2.0