node-qiitar

Node.js bindings for qiitar via napi-rs. Mirrors the core async API of node-keytar.

Platform

macOS only. Linux and Windows are not supported.

Build

cd crates/node-qiitar
npm install
npm run build              # release build → node-qiitar.darwin-{arch}.node

npm run build:debug produces an unoptimized build for faster iteration.

API

setPassword(service: string, account: string, password: string): Promise<void>
getPassword(service: string, account: string): Promise<string | null>
deletePassword(service: string, account: string): Promise<boolean>

Semantics match qiitar:

| Function | Resolves to | Behavior | | --- | --- | --- | | setPassword | void | Upserts. Existing entry for (service, account) is overwritten. | | getPassword | string \| null | null if no entry exists. | | deletePassword | boolean | false if no entry existed. |

Usage

const { setPassword, getPassword, deletePassword } = require('node-qiitar')

await setPassword('com.example.myapp', '[email protected]', 'hunter2')

const pw = await getPassword('com.example.myapp', '[email protected]')
// 'hunter2'

const deleted = await deletePassword('com.example.myapp', '[email protected]')
// true

From a separate project, install via filesystem reference:

npm install file:/path/to/qiitar/crates/node-qiitar

Errors

Promises reject with a JS Error whose message is prefixed with a fixed tag so callers can branch without parsing prose:

• [NotUtf8] ... — the stored bytes weren't valid UTF-8.
• [KeychainError] ... — an error from the underlying Keychain Services call.

errSecItemNotFound is not an error here; getPassword resolves to null and deletePassword resolves to false in that case.

Testing

npm run build
npm test

Tests run against the real user Keychain. Each test uses a unique service name and cleans itself up in a finally block.

Lint & format

JS/JSON formatting and linting use Biome. CI runs biome ci (the read-only CI mode); locally:

npm run lint        # biome ci .   — check only, fails on any issue
npm run lint:fix    # biome check --write .   — apply safe fixes + formatting

Configuration lives in biome.json. Generated files (index.js, index.d.ts, *.node) are excluded from checking.

Release

Releases publish to npm from GitHub Actions via Trusted Publisher (OIDC) with provenance. No NPM_TOKEN is stored in the repo; npmjs.com authenticates the workflow by its OIDC identity.

Workflow

.github/workflows/release.yml is triggered by pushing a tag matching node-qiitar-v*, or by manual workflow_dispatch. It:

1. Builds aarch64-apple-darwin on macos-14 and x86_64-apple-darwin on macos-13 in parallel, running npm test on each.
2. Uploads each .node artifact.
3. From ubuntu-latest, downloads both artifacts and runs npm publish. publishConfig.provenance: true in package.json adds the provenance attestation automatically.

Cutting a release

cd crates/node-qiitar
npm version patch --tag-version-prefix=node-qiitar-v   # or minor / major
cd ../..
git push
git push --tags

npm version bumps package.json, commits, and creates a tag of the form node-qiitar-v0.1.1. Pushing the tag fires the workflow.

To cut a release manually, edit package.json, commit, then:

git tag node-qiitar-v0.2.0
git push origin main node-qiitar-v0.2.0

Verifying

After the workflow completes, the package page on npmjs.com/package/node-qiitar should show a "Built and signed on GitHub Actions" badge linking to the workflow run.

One-time setup notes

• npm Trusted Publisher must be configured on the package's settings page, pointing at this repository's release.yml. Set up once; no maintenance after that.
• Maintainers do not need npm NPM_TOKEN credentials for releases.