feat: gap-closure items from the v7 plan (hk.pkl, WWDR warning, CONTRIBUTING)

Closes three misses from the original modernization plan that weren't
addressed in the main v7 commit chain.

1. hk.pkl: the Git 2.53 native hook config the plan described. Binds
   pre-commit to oxfmt + oxlint (auto-fix) and pre-push to `npm test`.
   Validated with `hk validate`. CLAUDE.md already documented `hk install`
   as the one-time setup; previously that left contributors with no-op
   hooks because the config file itself wasn't committed.

2. WWDR cert expiry runtime warning in src/lib/sign-manifest.ts. If the
   bundled WWDR cert is within 90 days of expiry (or already expired),
   emit a process warning at module load time. Uses `process.emitWarning`
   with distinct codes `WALLETPASS_WWDR_EXPIRED` /
   `WALLETPASS_WWDR_EXPIRING`, which integrates with Node's native
   warning machinery:
   - prints to stderr in the standard `(pid:xxx) [CODE] Name: msg` format
   - suppressible via `node --disable-warning=WalletPassWWDRExpiring`
   - interceptable via `process.on('warning', ...)`
   This is the guard that should prevent another 2023-style silent
   expiry. The 2013-2023 G1 cert expired in production for months
   before anyone noticed — the whole v7 revival effort started because
   of that.

3. CONTRIBUTING.md: documents the Conventional Commits rules (required
   for release-please to work correctly), the three quality gates, the
   hk setup for local hooks, and explicit scope guidance (no new runtime
   deps, no filesystem-required features, Wallet Orders out of scope).
   CLAUDE.md is for AI assistants; CONTRIBUTING.md is for humans.

Deliberately did NOT add a `postinstall` script to package.json — that
would pollute every consumer's `npm install` with hint text for a
maintainer-only tool. The hk install instructions are in CLAUDE.md and
CONTRIBUTING.md where they belong.

Remaining gaps from the plan, deferred to v7.1+:
- zip.ts fuzz tests (branch coverage)
- UpcomingPassInformationEntry + secondaryLogo schema
- oxlint --type-check flag (tsgo build step already catches this)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tinovyatkin

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to `@walletpass/pass-js`
+
+Thanks for wanting to help. This is a small library with a tight scope —
+generating valid Apple Wallet `.pkpass` files — so contributions that stay
+inside that scope and keep the dependency footprint minimal are most likely
+to land quickly.
+
+## Setup
+
+```sh
+# Prereqs: Node 24.12+ (see .nvmrc), npm 11+
+nvm use   # or: mise use
+npm ci
+npm run build && npm test
+```
+
+One-time Git hook wiring (optional but recommended — matches what CI runs):
+
+```sh
+# Install hk (https://hk.jdx.dev) — Rust binary, no npm footprint
+brew install hk           # or: cargo install hk, or: mise use hk
+hk install                # one-time wires native Git 2.53 hooks
+```
+
+Now `git commit` runs oxfmt + oxlint (auto-fix), and `git push` runs the
+test suite.
+
+## Commits: Conventional Commits are required
+
+Release automation (`release-please`) bumps the version and generates the
+changelog directly from commit messages. **Breaking the format breaks the
+release pipeline**, so please follow it:
+
+| Prefix | Bump | Changelog section | Example |
+|---|---|---|---|
+| `feat:` | minor | Features | `feat: add appLaunchURL mapping` |
+| `fix:` | patch | Bug Fixes | `fix: reject invalid Date in semantics` |
+| `perf:` | patch | Performance | `perf: cache CRC table at module load` |
+| `feat!:` or `BREAKING CHANGE:` footer | **major** | Features + BREAKING note | `feat!: drop Node < 24` |
+| `deps:` | patch | Dependencies | `deps: bump pkijs 3.4 → 3.5` |
+| `docs:`, `refactor:`, `test:`, `ci:`, `chore:`, `build:`, `style:` | — | hidden | `docs: clarify WWDR rotation flow` |
+
+Scopes are optional (`feat(nfc): ...`). Keep the subject line ≤ 72 chars.
+Body is free-form; put the "why" there, not the "what".
+
+## Before opening a PR
+
+All three quality gates must be green. They'll run in CI regardless; running
+them locally first saves a round-trip:
+
+```sh
+npm run build     # tsgo, must emit cleanly
+npm run lint      # oxlint (type-aware) + oxfmt --check
+npm test          # builds, then runs __tests__/ against dist/
+```
+
+If you touch cryptographic code in `src/lib/sign-manifest.ts`, also manually
+verify the round-trip on a real pkpass with a test cert — CLAUDE.md has the
+recipe under "Manual QA."
+
+## Scope
+
+Welcome:
+- Bug fixes (especially around Apple spec compliance or edge-case passes).
+- Schema additions that track current Apple Wallet documentation.
+- Documentation clarifications.
+- Test coverage expansion.
+
+Think twice or open an issue first:
+- New runtime dependencies — the v7 goal was to minimize these. We dropped
+  6 deps in the rewrite; please don't re-add surface area without a clear
+  case.
+- Order tracking (Wallet Orders / `order.json`) — a whole second package
+  format with its own certificate flow; out of scope for this library.
+- Features that require writing to the filesystem — the library should stay
+  bundler-friendly for Lambda / edge runtimes. Use Buffer/string APIs.
+
+## Architecture notes
+
+See [CLAUDE.md](./CLAUDE.md) for the non-obvious bits — why SHA-1 is
+deliberate in manifest hashing, how the WWDR cert is inlined for bundle
+safety, why tests import from `dist/` rather than `src/`, etc.

hk.pkl

@@ -0,0 +1,46 @@
+// hk (jdx/hk) — Git 2.53 native hook manager
+// See CLAUDE.md § "Git hooks (optional)" for install instructions.
+// Generated from `hk init`, customized for pass-js.
+
+amends "package://github.com/jdx/hk/releases/download/v1.44.3/hk@1.44.3#/Config.pkl"
+
+local linters = new Mapping<String, Step> {
+  // oxfmt is per-file, fast, and safe to auto-fix.
+  ["oxfmt"] {
+    glob = List("*.ts")
+    check = "oxfmt --check {{files}}"
+    fix = "oxfmt {{files}}"
+  }
+  // oxlint runs project-wide because type-aware mode needs the whole
+  // program (tsgo loads tsconfig.json). Gated on *.ts changes so it
+  // doesn't fire for README-only commits.
+  ["oxlint"] {
+    glob = List("*.ts")
+    check = "oxlint --type-aware"
+    fix = "oxlint --type-aware --fix"
+  }
+}
+
+hooks {
+  ["pre-commit"] {
+    fix = true
+    stash = "git"
+    steps = linters
+  }
+  ["pre-push"] {
+    steps = new Mapping<String, Step> {
+      // Full test suite including the build + openssl signing round-trip.
+      // Takes ~1s on a modern laptop; worth catching before a public push.
+      ["test"] {
+        check = "npm test"
+      }
+    }
+  }
+  ["fix"] {
+    fix = true
+    steps = linters
+  }
+  ["check"] {
+    steps = linters
+  }
+}

src/lib/sign-manifest.ts

@@ -76,6 +76,34 @@ const OID_RSA_ENCRYPTION = '1.2.840.113549.1.1.1';
 
 const APPLE_WWDR_CA = parsePkiCertificate(APPLE_WWDR_CA_PEM);
 
+// Emit a process warning if the bundled WWDR cert is within 90 days of
+// expiry (or already expired). The 2013–2023 G1 silently expired and every
+// downstream user shipped broken passes for months before anyone noticed —
+// this is the guard that should catch the next rotation.
+//
+// Uses process.emitWarning (rather than console.warn) so consumers can
+// silence or intercept it the standard Node way:
+//   node --disable-warning=WalletPassWWDRExpiring app.js
+//   process.on('warning', w => { if (w.code === 'WALLETPASS_WWDR_EXPIRED') ... })
+const WWDR_WARN_WINDOW_MS = 90 * 24 * 60 * 60 * 1000;
+const wwdrNotAfter = APPLE_WWDR_CA.notAfter.value;
+const msUntilExpiry = wwdrNotAfter.getTime() - Date.now();
+if (msUntilExpiry < WWDR_WARN_WINDOW_MS) {
+  const when = wwdrNotAfter.toISOString().slice(0, 10);
+  const days = Math.ceil(msUntilExpiry / (24 * 60 * 60 * 1000));
+  if (msUntilExpiry < 0) {
+    process.emitWarning(
+      `Bundled Apple WWDR certificate expired on ${when}. Signed passes will fail validation. Upgrade @walletpass/pass-js or override via APPLE_WWDR_CERT_PEM. See https://www.apple.com/certificateauthority/`,
+      { type: 'WalletPassWWDRExpired', code: 'WALLETPASS_WWDR_EXPIRED' },
+    );
+  } else {
+    process.emitWarning(
+      `Bundled Apple WWDR certificate expires on ${when} (${days} days). Upgrade @walletpass/pass-js before then to avoid silently shipping invalid passes.`,
+      { type: 'WalletPassWWDRExpiring', code: 'WALLETPASS_WWDR_EXPIRING' },
+    );
+  }
+}
+
 // ─── Public API ─────────────────────────────────────────────────────────────
 
 // Sign the manifest.json of an Apple Wallet pass bundle.