npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@formancy/data-identity

v0.3.0

Published

The host identity tokens Formancy Data verifies: a JWT checked offline under a pinned algorithm, against one key or a JSON Web Key Set read from a file, and the secret references a setting names. jose and Node, and nothing else.

Readme

@formancy/data-identity

The host identity tokens Formancy Data verifies: a JWT the host application signs for a person, checked offline under a pinned algorithm against one shared secret, one public key, or a JSON Web Key Set read from a file and read again whenever asked (0014, 0059).

It is the code @formancy/data-server verifies with, which the server re-exports, in a package of its own so that another product verifies the same tokens without installing a web server and two database drivers (0091). It depends on jose and Node's built-ins, and nothing else.

Licence. Source-available under the Formancy Data licence in LICENSE.md, like every package in this repository; see the licence table in the repository README.

What it exports

createIdentityVerifier(options)   // → (token) => Promise<{ ok: true, identity } | { ok: false, reason }>
readKeySet(text, algorithm)       // → KeySet, or throws KeySetRefusal
KeySet.fromSecret(secret)         // → KeySet: HS256 over the secret's UTF-8 bytes, at least 32 of them
KeySet.fromPem(pem, algorithm)    // → Promise<KeySet>: an SPKI public key, RS256, ES256 or EdDSA
openKeySetFile(path, algorithm)   // → Promise<{ current, readAgain }>
resolveSecret(reference, source?) // → Promise<string>, for env:NAME or file:/absolute/path
isKeySetAlgorithm(value)          // → whether it is RS256, ES256, EdDSA or HS256
oneKeySet(key)                    // → Promise<KeySet>, the set a one-key option verifies with

With their types: HostIdentity, IdentityOptions, IdentityOutcome, IdentityVerifier, OneKey, KeySetAlgorithm, KeySetChange, LeftOutKey, KeySetFile, KeySetReadAgain and SecretSource.

Verifying a token

import { createIdentityVerifier, openKeySetFile } from '@formancy/data-identity'

// The provider's published keys, copied into a file by the operator's own job.
// A file that does not parse, holds a private key, or a key under which
// anyone signs, throws a KeySetRefusal here, naming keys by kid or by place.
const file = await openKeySetFile('/run/identity/keys.json', 'RS256')

const verify = await createIdentityVerifier({
  key: { kind: 'key-set', keys: file.current },
  issuer: 'https://login.example/tenant',
  audience: 'formancy-report',
  attributes: { tenant: 'tid' },
})

// A set that is accepted replaces the one in force between tokens; one that
// is not leaves it, and the outcome says why, never quoting the file.
process.on('SIGHUP', () => void file.readAgain().then((outcome) => console.log(outcome)))

const outcome = await verify(token)
if (outcome.ok) {
  outcome.identity.actor // { id: the token's sub, roles: its roles claim }
  outcome.identity.attributes // { tenant: '3' }: a whole-number claim as its decimal string
} else {
  outcome.reason // jose's code, or a sentence naming a claim; never the token
}

One shared secret is { kind: 'secret', secret }, read from a reference with resolveSecret('env:HOST_SECRET'), and one public key is { kind: 'public-key', pem, algorithm }. Either ignores a token's kid. In a key set, a kid selects that key and no other; a token without one is tried against each key in force, in file order.

What it does not do

  • It fetches nothing. No key set URL, and no key a token names in its header (jku, x5u, jwk): an outbound request from inside a customer's network, and a key the token chooses.
  • It reads no setting. Which key, issuer, audience and claims to accept is the caller's to read and pass; the data server reads its FORMANCY_DATA_IDENTITY_* variables in its own identity-settings.ts. resolveSecret reads the environment or a file only for the reference it is handed.
  • It does not mint tokens. The host signs them.

src/identity.test.ts holds the verifier, src/identity-keys.test.ts what a key set accepts and refuses, src/identity-file.test.ts a file read again, src/secrets.test.ts that no error repeats a reference, and src/index.test.ts that the entry exports nothing more than the list above.

Licence

Source-available, not open source. See LICENSE.md: free to read, fork, evaluate, develop and test; a paid licence for production use.