@carecard/auth-util 3.1.12 → 3.1.15

package/.agents/skills/github-pr-merge-cleanup/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: github-pr-merge-cleanup
+description: Use only when the user explicitly asks for remote Git or GitHub PR work: reviewing remote mergeability, validating, merging, closing, deleting, or cleaning up a pull request branch.
+---
+
+# Pull Request Merge Close
+
+## Purpose
+
+Only after the user explicitly asks for remote Git or GitHub PR work, review, validate, merge, close, delete branch, and clean local state for a GitHub pull request targeting origin/development.
+
+## When To Use
+
+- Use only when the user explicitly asks to review mergeability, validate, merge, close, or clean up a GitHub pull request branch.
+
+## When Not To Use
+
+- Do not use for creating a new pull request; use the PR create/update skill.
+- Do not use when the user only asks for local code changes without PR merge work.
+
+## Remote Git Operations Guardrail
+
+Do not run remote Git or GitHub operations unless the current user request explicitly asks for that remote operation. This includes `git fetch`, `git pull`, `git push`, `git push --delete`, remote branch cleanup, GitHub API calls, and any `gh pr` command that creates, updates, readies, merges, closes, or cleans up a pull request. Do not infer permission from branch names, validation needs, prior workflow habits, or convenience; ask first when remote state would be useful but was not requested.
+
+## Relevant Files And Directories
+
+- Git branch state in this repository
+- GitHub pull requests viewed with `gh`
+- repository validation commands and `.husky` scripts
+
+## Coding Principles
+
+- Preserve the repository structure, naming style, module system, and local helper patterns.
+- Prefer readable, maintainable code with meaningful function, variable, file, and test names.
+- Avoid new dependencies unless the existing stack cannot reasonably solve the task and the user confirms the tradeoff.
+
+## Testing Expectations
+
+- Run repository validation before PR creation or merge when code behavior changed.
+- Confirm the branch is clean except intended changes before finishing.
+
+## Safety Constraints
+
+- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task explicitly requires it.
+- Do not revert or overwrite user changes; stage only files related to the requested skill or instruction update.
+- Never suppress errors, lint failures, type failures, security failures, or failing tests; fix the underlying issue or report the blocker.
+
+## Commit Continuation Rule
+
+Do not amend existing commits unless the user explicitly asks for an amend. If
+hook, formatter, documentation, skill, validation, or review follow-up changes
+appear after a commit, stage only the intended files and make a new commit with
+a clear message.
+
+## Scope
+
+Use this skill from the root of the repository that owns the pull request. The
+repository must use GitHub CLI, have a remote base branch, and have the target
+branch available locally or on `origin`.
+
+Default terms:
+
+- Base branch: `development` when `origin/development` exists, otherwise the
+  repository default branch.
+- Target branch: the current branch unless the user names another branch.
+- Pull request: the open PR whose head is the target branch and whose base is
+  the base branch.
+
+Do not continue automatically when:
+
+- `gh auth status` fails.
+- The target branch is detached or is the base branch.
+- The working tree has uncommitted changes that are not part of the requested
+  PR cleanup.
+- No open PR exists for the target branch.
+- A rebase or validation fix would require behavior changes instead of coding
+  criteria cleanup.
+
+## Workflow
+
+1. Capture the base branch, target branch, PR number, and protection state:
+
+   ```sh
+   gh auth status
+   base="development"
+   git ls-remote --exit-code --heads origin development >/dev/null 2>&1 || \
+     base="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
+   target_branch="$(git branch --show-current)"
+   test -n "$target_branch"
+   test "$target_branch" != "$base"
+   git status --short
+   git fetch origin "$base" --prune
+   pr_number="$(gh pr list --head "$target_branch" --base "$base" --state open --json number --jq '.[0].number // empty')"
+   test -n "$pr_number"
+   protected="$(gh api "repos/{owner}/{repo}/branches/$target_branch" --jq '.protected' 2>/dev/null || echo false)"
+   ```
+
+   If the PR head branch is not local, create a local branch from the remote
+   head before continuing.
+
+2. Check mergeability before changing history:
+
+   ```sh
+   gh pr view "$pr_number" --json mergeStateStatus,mergeable,headRefName,baseRefName
+   if git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-merge-close-merge-tree.out
+   then
+     merge_conflict_detected=false
+   else
+     merge_conflict_detected=true
+   fi
+   ```
+
+3. If a merge conflict is detected, rebase the target branch on the fresh base
+   branch. Abort and stop if the rebase conflicts:
+
+   ```sh
+   if [ "$merge_conflict_detected" = true ]; then
+     if git rebase "origin/$base"; then
+       git push --force-with-lease -u origin "$target_branch"
+     else
+       git rebase --abort
+       echo "Rebase conflicted; aborted without merging."
+       exit 1
+     fi
+   fi
+   ```
+
+   Do not resolve rebase conflicts unless the user explicitly asks.
+
+4. Load and apply all relevant repository skills before merging:
+   - Read the repository's `.agents/skills/**/SKILL.md` files that apply to the
+     changed code, plus shared workspace standards when present.
+   - Compare the target branch against the base with
+     `git diff --stat "origin/$base...HEAD"` and inspect changed files.
+   - Check whether the target branch satisfies the applicable coding,
+     architecture, validation, security, and style criteria from those skills.
+   - Run the validation commands required by the skills and repository hooks.
+   - If criteria are not met and the fix does not change functionality, make the
+     minimal cleanup, stage only intended files, commit to the target branch,
+     and push the target branch.
+   - If meeting the criteria would change behavior, stop and report the gap.
+
+5. Confirm the PR is still mergeable after validation changes:
+
+   ```sh
+   git fetch origin "$base" --prune
+   git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-merge-close-final-merge-tree.out
+   gh pr checks "$pr_number"
+   ```
+
+6. Merge the PR with GitHub CLI. Delete the remote target branch only when it is
+   not protected:
+
+   ```sh
+   if [ "$protected" = true ]; then
+     gh pr merge "$pr_number" --squash --admin
+   else
+     gh pr merge "$pr_number" --squash --admin --delete-branch
+   fi
+   ```
+
+7. Clean up the local repository after merge:
+
+   ```sh
+   git fetch origin "$base" --prune
+   git switch "$base"
+   git pull --ff-only origin "$base"
+   git branch -d "$target_branch" || git branch -D "$target_branch"
+   git ls-remote --heads origin "$target_branch"
+   ```
+
+8. Final response should include the PR URL, whether a rebase was performed,
+   what validation and skill checks ran, whether any cleanup commit was added,
+   whether the remote target branch was deleted or protected, and whether local
+   development is up to date.

package/.agents/skills/github-pr-merge-cleanup/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: 'GitHub PR Merge And Cleanup'
+  short_description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: merge, close, delete, or clean up a PR branch.'
+  brand_color: '#0F766E'
+  default_prompt: 'Use $github-pr-merge-cleanup when this task matches the skill scope.'

package/.agents/skills/pkg-auth-util-auth-crypto-library/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: pkg-auth-util-auth-crypto-library
+description: Use when changing pkg-auth-util auth, password, JWT, crypto, key, exported API, types, or package validation behavior.
+---
+
+# Package Auth Util
+
+## Purpose
+
+CareCard auth utility package for JWT creation/verification primitives, password hashing, crypto helpers, key generation, and tests.
+
+## When To Use
+
+- Use when changing pkg-auth-util auth, password, JWT, crypto, key, exported API, types, or package validation behavior.
+- Pair with `carecard-workspace-standards` when the task affects shared CareCard conventions or cross-repository contracts.
+
+## When Not To Use
+
+- Do not use for service-local behavior that should remain inside one API or app.
+- Do not change package public APIs without updating consumers and compatibility tests.
+
+## Relevant Files And Directories
+
+- package entry files
+- `src` when present
+- `test`
+- `package.json`
+- `package-lock.json`
+- `.husky`
+
+## Coding Principles
+
+- Preserve the repository structure, naming style, module system, and local helper patterns.
+- Prefer readable, maintainable code with meaningful function, variable, file, and test names.
+- Avoid new dependencies unless the existing stack cannot reasonably solve the task and the user confirms the tradeoff.
+- Keep public exports stable and update CommonJS, ESM, TypeScript declaration, and compatibility surfaces together when present.
+
+## Testing Expectations
+
+- Write or update package tests before behavior or public API changes.
+- Include type/export compatibility tests where the package already has them.
+- Run package test, lint, type, and Husky validation commands required by the changed area.
+
+## Safety Constraints
+
+- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task explicitly requires it.
+- Do not revert or overwrite user changes; stage only files related to the requested skill or instruction update.
+- Never suppress errors, lint failures, type failures, security failures, or failing tests; fix the underlying issue or report the blocker.
+- Do not log or expose secrets, JWTs, passwords, credentials, private keys, sensitive personal data, SQL internals, or stack traces.
+
+## Overview
+
+Use this skill when working inside `pkg-auth-util`, the `@carecard/auth-util`
+package. It provides core authentication and authorization utilities for the
+CareCard ecosystem.
+
+Use `$carecard-workspace-standards` for shared workspace, dependency, package,
+testing, and security rules. Legacy `pkg-auth-util/.codex` and
+`pkg-auth-util/.junie` guidance has been migrated into these skills; do not
+depend on those folders being present.
+
+## Non-Negotiable Rules
+
+- Never use TypeScript type `any`. Use precise exported interfaces, index
+  signatures with `unknown`, generics, explicit unions, or explicit narrowing.
+- Follow the existing CommonJS utility-package style, Mocha tests, TypeScript
+  declaration tests, and CareCard package conventions.
+- Follow existing naming conventions:
+  - Public functions use camelCase.
+  - Internal helpers use the established underscore prefix.
+- Keep public exports in `index.js`, declarations in `index.d.ts`,
+  implementation modules in `lib`, and tests in `test`.
+- Use Test-Driven Development. Add or update Mocha and type tests before
+  changing behavior or exported API.
+- Never suppress errors, type errors, linter warnings, crypto failures, or
+  failing tests. Fix the cause.
+- Do not add dependencies unless absolutely required. Ask for confirmation first
+  with the reason and tradeoff.
+- Before finalizing work, run every direct script in `.husky`. Do not bypass
+  Husky.
+
+## Package Scope
+
+- `index.js` is the centralized public export surface.
+- `index.d.ts` must stay aligned with every public export in `index.js`.
+- `lib/jwtUtilAuth.js` owns JWT creation, service-to-service JWT creation,
+  verification, and decomposition.
+- `lib/pwdUtilAuth.js` owns password hashing and saved-hash verification.
+- `lib/cryptoUtilAuth.js` wraps Node.js `crypto` primitives for signing,
+  verifying, generating HMACs, and salts.
+- `lib/keyGen.js` owns Ed25519 and RSA key generation.
+- `lib/stringUtilAuth.js` owns legacy base64, base64-url-safe, JWT, and
+  password-hash string parsing helpers.
+- Keep direct exports preferred and deprecated nested exports backward
+  compatible unless a breaking change is explicitly requested.
+- Preserve CommonJS exports unless the repository intentionally migrates module
+  systems.
+
+## JWT Layer
+
+- Use EdDSA/Ed25519 as the default JWT algorithm unless a task explicitly
+  changes crypto behavior.
+- Preserve standardized headers and payload behavior, including automatic `iat`
+  and `exp` population where the existing API does that.
+- Keep service-to-service JWT creation here, not in `@carecard/jwt-read`.
+  Public service-token creation exports are `jwtCreateServiceToken` and
+  `jwtCreateServiceAuthorizationHeader`.
+- Do not silently change token timing behavior, token formats, JWT string
+  assembly, signature verification semantics, or decomposition return shapes.
+- Expected parse and verify failures should return `null` or `false` where the
+  current public API does so.
+
+## Password And Crypto Layer
+
+- Preserve the HMAC-based password hashing behavior.
+- Preserve the saved password hash string format:
+
+  ```text
+  $1$base64(algorithm)$base64(hash)$base64(salt)$
+  ```
+
+- Always handle salt automatically when creating new password hashes.
+- Do not silently change cryptographic defaults, password hash string format,
+  salt behavior, or key output format.
+- Prefer Node.js `crypto` primitives already used by the package over new
+  dependencies.
+
+## String Utilities
+
+- Use `stringUtilAuth` for base64 and URL-safe string transformations to keep
+  parsing and serialization consistent.
+- Keep legacy formatted string parsing behavior backward-compatible.
+- Cover edge cases for malformed JWT strings, malformed password hashes, bad
+  base64 input, missing segments, and unsupported algorithms when these paths
+  change.
+
+## Security And Error Handling
+
+- Treat JWT signing, verification, password hashing, salts, secrets, private
+  keys, public keys, reset tokens, and key generation as security-sensitive.
+- Do not log secrets, private keys, tokens, password hashes, salts, raw
+  payloads, full JWT payloads, or credentials.
+- Preserve the current utility style: expected parse, verify, and hash failures
+  should fail gracefully by returning `null` or `false` where the existing API
+  does so.
+- Use `try/catch` inside utility functions where existing functions fail
+  gracefully instead of throwing uncaught exceptions.
+- Do not broaden catch blocks in a way that hides unexpected implementation
+  errors in callers that currently expect throws.
+
+## Types And Exports
+
+- Keep `index.d.ts` in sync with every public export in `index.js`.
+- Avoid new loose index signatures. If payloads need custom claims, type them as
+  `Record<string, unknown>` or a named claim interface.
+- Keep deprecated APIs marked as deprecated and prefer direct export examples in
+  docs and tests.
+- Update type tests whenever public exports, overloads, return values, payload
+  shapes, or declaration behavior changes.
+
+## Tests
+
+- Use Mocha for runtime tests under `test`.
+- Every implementation module in `lib` should have matching tests under `test`.
+  For example, `lib/jwtUtilAuth.js` should be covered by
+  `test/jwtUtilAuth.test.js`.
+- `test/index.test.js` should cover scenarios through the public exports from
+  `index.js`.
+- `test/types.test.ts` verifies TypeScript declarations with `tsc`.
+- Cover success and failure cases for JWT parsing, signature verification,
+  password hashing, saved-hash verification, key generation, base64 conversion,
+  URL-safe conversion, and string parsing.
+- Keep tests deterministic and avoid external services.
+
+## Validation
+
+Useful commands:
+
+- `npm run lint`
+- `npm run lint:fix`
+- `npm run format`
+- `npm run format:check`
+- `npm run test`
+- `npm run test:types`
+- `npm run test:coverage`
+- `npm run test:All`
+
+Before pushing or finalizing, run every direct `.husky` script. The current
+`.husky/pre-commit` runs:
+
+```bash
+npm run lint:fix
+npm run format
+npm run test:All
+```
+
+If any validation command cannot run, report the exact command, failure reason,
+and remaining risk.
+
+## Remote Git Operations Guardrail
+
+Do not run remote Git or GitHub operations unless the current user request explicitly asks for that remote operation. This includes `git fetch`, `git pull`, `git push`, `git push --delete`, remote branch cleanup, GitHub API calls, and any `gh pr` command that creates, updates, readies, merges, closes, or cleans up a pull request. Do not infer permission from branch names, validation needs, prior workflow habits, or convenience; ask first when remote state would be useful but was not requested.
+
+## Agent Guidance Git Workflow
+
+When this skill or any repository-owned `.agents` guidance changes, use the
+repository's agents-only Git workflow:
+
+1. Work from the affected repository root and confirm only intended `.agents`
+   files changed.
+2. Use `development` as the base branch when `origin/development` exists;
+   otherwise use the repository's default base branch, usually `main`.
+3. Create or update `feature/codex` from the updated remote base branch and
+   commit all the changed `.agents` guidance files there.
+4. Push `feature/codex`, create or reuse a pull request into the base branch,
+   and mark the pull request ready for review with `gh pr ready <number>`.
+5. Squash-merge with administrator privileges and delete the remote branch:
+
+   ```sh
+   gh pr merge <number> --squash --admin --delete-branch
+   ```
+
+6. After merge, update the local base branch and remove the local feature
+   branch:
+
+   ```sh
+   git fetch origin <base> --prune
+   git switch <base>
+   git pull --ff-only origin <base>
+   git branch -d feature/codex
+   git ls-remote --heads origin feature/codex
+   ```
+
+Do not commit or push `.agents` guidance changes directly from `development`
+or `main`. Do not stage unrelated files, generated output, dependency folders,
+build artifacts, logs, or `.DS_Store`.

package/.agents/skills/pkg-auth-util-auth-crypto-library/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Package Auth Util Auth Crypto Library'
+  short_description: 'Use when changing pkg-auth-util auth, password, JWT, crypto, key, exported API, types, or package validation behavior.'
+  default_prompt: 'Use $pkg-auth-util-auth-crypto-library when this task matches the skill scope.'

package/.agents/skills/software-design-patterns-and-clean-code/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: software-design-patterns-and-clean-code
+description: Use every time before coding, refactoring, debugging, or reviewing in this repository, alongside all other applicable skills, to apply pragmatic software design patterns, SOLID, Clean Code, and testable architecture.
+---
+
+# Software Design Patterns And Clean Code
+
+## Purpose
+
+Use this skill with every coding, refactoring, debugging, or review task in
+this repository. It supplements repository-specific skills; follow both, and
+let the more specific skill decide file locations, framework conventions,
+validation commands, and API contracts.
+
+## Core Principles
+
+- Prefer simple, maintainable, readable implementation over clever abstraction.
+- Use Gang of Four design patterns only when they reduce real complexity,
+  improve clarity, or make behavior easier to test.
+- Follow SOLID principles, especially Single Responsibility and Dependency
+  Inversion where they improve maintainability.
+- Keep clear separation of concerns between routing, orchestration, domain
+  logic, persistence, validation, formatting, and side effects.
+- Apply DRY, KISS, and YAGNI. Remove meaningful duplication, keep solutions
+  direct, and avoid speculative generalization.
+- Favor small, composable functions with meaningful names and explicit inputs.
+- Prefer pure functions for calculations, mapping, validation, and transforms
+  when practical.
+- Keep side effects minimal, localized, and easy to identify.
+- Use explicit error handling. Do not swallow failures or hide actionable
+  error context.
+- Design code so behavior can be tested through focused unit, integration, or
+  service tests without fragile setup.
+- Avoid unnecessary dependencies. Use existing language, framework, and local
+  helper capabilities before adding packages.
+
+## Function Comments
+
+For every new or modified function, method, or exported callback, add a short
+comment immediately above it explaining the main pattern or principle being
+applied. Keep the comment accurate and specific to the function.
+
+Use the host language's normal comment syntax. Examples:
+
+```ts
+// Pattern: Single Responsibility - validates user input only.
+function validateUserInput(...) { ... }
+
+// Pattern: Pure Function - deterministic output with no side effects.
+function calculateTotal(...) { ... }
+
+// Pattern: Dependency Inversion - depends on an injected repository contract.
+async function loadProfile(...) { ... }
+```
+
+## Working Rules
+
+- Do not violate these coding principles unless there is no reasonable
+  alternative.
+- If a principle must be violated, include a short explanation in the code
+  review or final summary.
+- Refactor touched existing code to follow these patterns and principles when
+  doing so is safe and related to the requested change.
+- Do not use this skill as a reason for broad unrelated rewrites.
+- Before introducing an abstraction or design pattern, confirm it removes real
+  complexity compared with a straightforward function or module.
+- Prefer dependency inversion at boundaries such as databases, external
+  services, clocks, file systems, queues, and network calls when it improves
+  testability or substitution.
+- Keep interfaces and abstractions narrow. Do not create generic layers that
+  only have one trivial implementation unless they clarify a boundary.
+- Preserve the repository's existing style, naming, module system, and testing
+  approach.

package/.codex/config.toml

@@ -0,0 +1,2 @@
+approval_policy = "never"
+sandbox_mode = "danger-full-access"

package/.prettierignore

@@ -0,0 +1,17 @@
+dist/
+coverage/
+node_modules/
+build/
+*.min.js
+.github
+.husky
+dist
+.gitignore
+.npmignore
+.prettierignore
+.prettierrc.js
+eslint.config.mjs
+jest.config.js
+package.json
+readme.md
+rename-cjs.js

package/.prettierrc.cjs

@@ -0,0 +1,32 @@
+/** @type {import('prettier').Config} */
+module.exports = {
+  // Core formatting
+  printWidth: 100,
+  tabWidth: 2,
+  useTabs: false,
+  semi: true,
+  singleQuote: true,
+  trailingComma: 'all',
+  bracketSpacing: true,
+  bracketSameLine: true,
+  arrowParens: 'avoid',
+
+  // Line endings (important for cross-platform + CI)
+  endOfLine: 'auto',
+
+  // Language-specific overrides
+  overrides: [
+    {
+      files: '*.json',
+      options: {
+        printWidth: 80,
+      },
+    },
+    {
+      files: '*.md',
+      options: {
+        proseWrap: 'preserve',
+      },
+    },
+  ],
+};

package/.prettierrc.js

@@ -0,0 +1,12 @@
+module.exports = {
+  arrowParens: 'avoid',
+  bracketSameLine: true,
+  bracketSpacing: true,
+  singleQuote: true,
+  trailingComma: 'all',
+  printWidth: 140,
+  useTabs: false,
+  endOfLine: 'auto',
+  importOrderSeparation: true,
+  importOrderSortSpecifiers: true,
+};

package/eslint.config.mjs

@@ -0,0 +1,14 @@
+import { defineConfig, globalIgnores } from 'eslint/config';
+
+const eslintConfig = defineConfig([
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    '.next/**',
+    'out/**',
+    'build/**',
+    'next-env.d.ts',
+    'node_modules/**',
+  ]),
+]);
+
+export default eslintConfig;