@sd-jwt/core 0.20.1 → 0.21.0-alpha-20260916100413

package/LICENSE

@@ -1,4 +1,4 @@
-                                 Apache License
+                                Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 
@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/README.md

@@ -1,106 +1,108 @@
-![License](https://img.shields.io/github/license/openwallet-foundation/sd-jwt-js.svg)
-![NPM](https://img.shields.io/npm/v/%40sd-jwt%2Fcore)
-![Release](https://img.shields.io/github/v/release/openwallet-foundation/sd-jwt-js)
-![Stars](https://img.shields.io/github/stars/openwallet-foundation/sd-jwt-js)
+# @sd-jwt/core
 
-# SD-JWT Implementation in JavaScript (TypeScript)
-
-## SD-JWT Core
-
-### About
+[![npm version](https://img.shields.io/npm/v/@sd-jwt/core)](https://npmjs.com/package/@sd-jwt/core)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/LICENSE)
 
 Core library for [Selective Disclosure for JWTs (SD-JWT) — RFC 9901](https://www.rfc-editor.org/rfc/rfc9901.html).
 
-This package provides types, utilities, encoding/decoding, presentation, and the main `SDJwtInstance` class — everything needed to issue, present, and verify SD-JWTs.
-
-Check the detail description in our github [repo](https://github.com/openwallet-foundation/sd-jwt-js).
-
-### Installation
+This package provides types, utilities, encoding/decoding, presentation, and the main `SDJwtInstance` class — everything needed to issue, present, and verify SD-JWTs. For [SD-JWT-based Verifiable Credentials](https://datatracker.ietf.org/doc/draft-ietf-oauth-sd-jwt-vc/), use [`@sd-jwt/sd-jwt-vc`](../sd-jwt-vc), which is built on top of this package.
 
-To install this project, run the following command:
+## Installation
 
 ```bash
-# using npm
+# Using npm
 npm install @sd-jwt/core
 
-# using yarn
+# Using pnpm
+pnpm add @sd-jwt/core
+
+# Using yarn
 yarn add @sd-jwt/core
+```
 
-# using pnpm
-pnpm install @sd-jwt/core
+## Quick Start
+
+```typescript
+import Crypto from 'node:crypto'
+import { SDJwtInstance } from '@sd-jwt/core'
+
+// Bring your own crypto – any Signer / Verifier / Hasher that fits the interface
+const { privateKey, publicKey } = Crypto.generateKeyPairSync('ed25519')
+
+const sdjwt = new SDJwtInstance({
+  signer: async (data) => {
+    const sig = Crypto.sign(null, Buffer.from(data), privateKey)
+    return Buffer.from(sig).toString('base64url')
+  },
+  verifier: async (data, sig) => {
+    return Crypto.verify(null, Buffer.from(data), publicKey, Buffer.from(sig, 'base64url'))
+  },
+  signAlg: 'EdDSA',
+  hasher: async (data, alg) => {
+    return new Uint8Array(Crypto.createHash(alg.replace('-', '')).update(data).digest())
+  },
+  hashAlg: 'sha-256',
+  saltGenerator: async () => Crypto.randomBytes(16).toString('base64url'),
+})
+
+// Issue
+const credential = await sdjwt.issue(
+  { firstname: 'John', lastname: 'Doe', ssn: '123-45-6789' },
+  { _sd: ['firstname', 'lastname', 'ssn'] }
+)
+
+// Present (disclose only firstname)
+const presentation = await sdjwt.present(credential, { firstname: true })
+
+// Verify
+const { payload } = await sdjwt.verify(presentation)
+console.log(payload) // { firstname: 'John', ... }
 ```
 
-Ensure you have Node.js installed as a prerequisite.
+## Examples
 
-### Usage
+Runnable examples are available in [`examples/sd-jwt/core`](../../examples/sd-jwt/core). Run them from the repository root:
 
-The library can be used to create sd-jwt based credentials. To be compliant with the `sd-jwt-vc` standard, you can use the `@sd-jwt/sd-jwt-vc` that is implementing this spec.
-If you want to use the pure sd-jwt class or implement your own sd-jwt credential approach, you can use this library.
+```bash
+pnpm tsx examples/sd-jwt/core/basic.ts
+```
 
-### Dependencies
+See the [SD-JWT examples overview](../../examples/sd-jwt/README.md) for the full list.
 
-- [@owf/identity-common](https://www.npmjs.com/package/@owf/identity-common)
+## Security
 
-### Verification
+- [x] [Mandatory Signing of the Issuer-signed JWT](https://www.rfc-editor.org/rfc/rfc9901.html#name-mandatory-signing-of-the-is)
+- [x] [Manipulation of Disclosures](https://www.rfc-editor.org/rfc/rfc9901.html#name-manipulation-of-disclosures)
+- [x] [Entropy of the salt](https://www.rfc-editor.org/rfc/rfc9901.html#name-entropy-of-the-salt)
+- [x] [Minimum length of the salt](https://www.rfc-editor.org/rfc/rfc9901.html#name-minimum-length-of-the-salt)
+- [x] [Choice of a Hash Algorithm](https://www.rfc-editor.org/rfc/rfc9901.html#name-choice-of-a-hash-algorithm)
+- [x] [Key Binding](https://www.rfc-editor.org/rfc/rfc9901.html#name-key-binding)
+- [x] [Blinding Claim Names](https://www.rfc-editor.org/rfc/rfc9901.html#name-blinding-claim-names)
+- [x] [Selectively-Disclosable Validity Claims](https://www.rfc-editor.org/rfc/rfc9901.html#name-selectively-disclosable-val)
+- [x] [Issuer Signature Key Distribution and Rotation](https://www.rfc-editor.org/rfc/rfc9901.html#name-issuer-signature-key-distri)
+- [x] [Forwarding Credentials](https://www.rfc-editor.org/rfc/rfc9901.html#name-forwarding-credentials)
+- [x] [Integrity of Presentation](https://www.rfc-editor.org/rfc/rfc9901.html#name-integrity-of-presentation)
+- [x] [Explicit Typing](https://www.rfc-editor.org/rfc/rfc9901.html#name-explicit-typing)
+- [x] [Duplicate Digest Rejection (Section 7.1 step 4)](https://www.rfc-editor.org/rfc/rfc9901.html#section-7.1)
+- [x] [Unreferenced Disclosure Rejection (Section 7.1 step 5)](https://www.rfc-editor.org/rfc/rfc9901.html#section-7.1)
+- [x] [Claim Name Collision Detection (Section 7.1 step 3c.ii.3)](https://www.rfc-editor.org/rfc/rfc9901.html#section-7.1)
 
-The library provides two verification approaches:
+## Platform Support
 
-#### Standard Verification (Fail-Fast)
+This library is **platform agnostic** and works in:
 
-The `verify()` method throws an error immediately when the first validation failure is encountered:
+- ✅ Node.js (>=20)
+- ✅ Browsers (modern browsers with ES2020 support)
+- ✅ React Native
 
-```typescript
-try {
-  const result = await sdjwt.verify(credential);
-  console.log('Verified payload:', result.payload);
-} catch (error) {
-  console.error('Verification failed:', error.message);
-}
-```
+A global `TextEncoder` and `TextDecoder` must be available. See the [React Native notes](../identity-common/README.md#react-native) if you need a polyfill.
 
-#### Safe Verification (Collect All Errors)
+Cryptographic operations (signing, verification, hashing, salt generation) are provided as callbacks. [`@owf/crypto`](https://github.com/openwallet-foundation-labs/identity-common-ts/tree/main/packages/crypto) provides Web Crypto based implementations.
 
-The `safeVerify()` method collects all validation errors instead of failing on the first one. This is useful when you want to show users all issues with a credential at once:
+## Contributing
 
-```typescript
-import type { SafeVerifyResult, VerificationError } from '@sd-jwt/core';
-
-const result = await sdjwt.safeVerify(credential);
-
-if (result.success) {
-  // Verification succeeded
-  console.log('Verified payload:', result.data.payload);
-  console.log('Header:', result.data.header);
-  if (result.data.kb) {
-    console.log('Key binding:', result.data.kb);
-  }
-} else {
-  // Verification failed - inspect all errors
-  for (const error of result.errors) {
-    console.error(`[${error.code}] ${error.message}`);
-    if (error.details) {
-      console.error('Details:', error.details);
-    }
-  }
-}
-```
+See the [Contributing Guide](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/CONTRIBUTING.md) for details on how to contribute to this project.
+
+## License
 
-##### Error Codes
-
-The `safeVerify()` method returns errors with the following codes:
-
-| Code | Description |
-|------|-------------|
-| `HASHER_NOT_FOUND` | Hasher function not configured |
-| `VERIFIER_NOT_FOUND` | Verifier function not configured |
-| `INVALID_SD_JWT` | SD-JWT structure is invalid or cannot be decoded |
-| `INVALID_JWT_FORMAT` | JWT format is malformed |
-| `JWT_NOT_YET_VALID` | JWT `iat` or `nbf` claim is in the future |
-| `JWT_EXPIRED` | JWT `exp` claim is in the past |
-| `INVALID_JWT_SIGNATURE` | Signature verification failed |
-| `MISSING_REQUIRED_CLAIMS` | Required claim keys are not present |
-| `KEY_BINDING_JWT_MISSING` | Key binding JWT required but not present |
-| `KEY_BINDING_VERIFIER_NOT_FOUND` | Key binding verifier not configured |
-| `KEY_BINDING_SIGNATURE_INVALID` | Key binding signature verification failed |
-| `KEY_BINDING_SD_HASH_INVALID` | Key binding `sd_hash` does not match |
-| `UNKNOWN_ERROR` | An unexpected error occurred |
+This project is licensed under the [Apache License Version 2.0](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/LICENSE) (Apache-2.0).